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Preface 



Organization 



This publication is a reference manual and contains the macro instructions that 
are used for the virtual storage access method (VSAM). It is intended for 
programmers who use VSAM macro instructions, access method services 
commands, or JCL to process data. 



This publication contains the following major sections: 

• Chapter 1, "Macro Instruction Return Codes and Reason Codes," contains 
return codes for macros used to open and close data sets, manage control 
blocks, and issue data management requests. 

• Chapter 2, "VSAM Macro Formats and Examples," describes the syntax of 
each macro and includes coded examples. 

• Appendix A, "Format of Macros," summarizes, for ease of reference, the 
format of the macros used to communicate with VSAM. 

• Appendix S, "list, Execute, and Generate Forms ©f Macros," explains how 
to code reentrant programs with the macros that generate, modify, test, and 
display control blocks at execution. 

• Appendix C, "Operand Notation," defines the terms used to describe the 
operand notation used in the macros that generate, modify, test, and display 
control blocks at program execution time. 

• Appendix D, "Building Parameter Lists," describes the standard way to 
build parameter lists. 

• "Glossary of Terms and Abbreviations" defines VSAM terms. 

• Index is a subject index to this publication. 
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Prerequisite Knowledge 



Readers of this publication are assumed to have a programming background that 
includes: 

• VSAM data management 

• Catalog administration 

• Job control language 



Required Publications 



You should be familiar with the information presented in the following 
publications: 

• MVS/Extended Architecture Catalog Administration Guide, GC26-4138, 
describes the administration of tasks for catalogs and how to use the access 
method services commands to manipulate catalogs, and the objects cataloged 
in them* 

• MVS/Extended Architecture Data Facility Product Version 2: Customization, 
GC26-4267, contains consolidated customization information for the DFP 
library. 

• M VS I Extended Architecture JCL User's Guide, GC28- 1 35 1 , and 

MVSj Extended Architecture JCL Reference, GC28-1352, describes the JCL 
parameters referred to in this publication and describes dynamic allocation. 

• MVS I Extended Architecture Message Library: System Messages, Volumes 1 
and 2, GC28-1376 and GC28-1377, provides a complete listing of the 
messages issued by VSAM. 

• MVSj Extended Architecture VSAM Administration Guide, GC26-4151, 
describes how to use VSAM. 

• MVS/Extended Architecture VSAM Logic, LY26-3970, describes the internal 
logic of VSAM. 



Related Publications 

Within the text, references are made to the publications listed in the table below: 
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Short Title 


Publication Title 


Order Number 


Access Method 

Services 

Reference 


MVSf Extended Architecture 
Integrated Catalog 
Administration: Access Method 
Services Reference 

MVS J Extended Architecture 
VSAM Catalog 

Administration: Access Method 
Services Reference 


GC26-4135 
GC26-4136 


Catalog 

Administration 

Guide 


MVS /Extended Architecture 
Catalog Administration Guide 


GC26-4138 


Checkpoint/ 
Restart User's 
Guide 


MVS /Extended Architecture 
Checkpoint /Restart User's 
Guide 


GC26-4139 


Data Facility 

Product: 

Customization 


MVS/ Extended Architecture 
Data Facility Product Version 
2: Customization 


GC26-4267 


Data 

Administration: 

Macro 

Instruction 

Reference 


MVS '/Extended Architecture 
Data Administration: Macro 
Instruction Reference 


GC26-4141 


Data 
Areas— JES2 


M VS/ Extended Architecture 
Data Areas -JES 2 


LYB8-1191 


Data 

Areas -JFS3 


M VS/ Extended Architecture 
Data Areas -JES 3 


LYB8-1195 


Data Facility 
Product: Master 
Index 


M VS/ Extended Architecture 
Data Facility Product Version 
2: Master Index 


GC26-4146 


Data Facility 
Product: 
Planning Guide 


M VS/ Extended Architecture 
Data Facility Product Version 
2: Planning Guide 


GC26-4147 


Debugging 
Handbook 


M VS/ Extended Architecture 
System Programming Library: 
Debugging Handbook, 
Volumes 1 through 5 


LC28-1164 1 
LC28-1165 
LC28-1166 
LC28-1167 
LC28-1168 


Introduction to 
the IBM 3850 
Mass Storage 
System 


Introduction to the IBM 3850 
Mass Storage System (MSS) 


GA32-0028 


JCL Users 
Guide 


MVS/ Extended Architecture 
JCL User's Guide 


GC28-1351 


JCL Reference 


MVS/ Extended Architecture 
JCL Reference 


GC28-1352 



Note: 



1 All five volumes may be ordered under one order number, LBOF-1015. 



Preface V 



Short Title 


Publication Title 


Order Number 


OS/VS Mass 
Storage System 
Services: 
Reference 
Information 


OS/ VS Mass Storage System 
(MSS) Services: Reference 
Information 


GC35-0017 


RACF General 

Information 

Manual 


OS/ VS2 MVS Resource Access 
Control Facility (RACF): 
General Information Manual 


GC28-0722 


Supervisor 
Services and 
Macro 
Instructions 


MVS J Extended Architecture 
System Programming Library: 
Supervisor Services and Macro 
Instructions 


GC28-1154 


System Messages 


MVS/ Extended Architecture 
Message Library: System 
Messages, Volumes 1 and 2 


GC28-1376 

and 

GC28-1377 


System 
Modifications 


M VS/ Extended A rchitecture 
System Programming Library: 
System Modifications 


GC28-1152 


TSO Command 

language 

Reference 


OS/VS 2 TSO Command 
Language Reference with 
MVS/Cxtended Architecture 
supplement 


GC28-0646 
SD23-0259 


TSO Terminal 
User's Guide 


MVS/ Extended Architecture 
TSO Terminal User's Guide 


GC28-1274 


VSAM 

Administration 
Guide 


MVS /Extended Architecture 
VSAM Administration Guide 


GC26-4151 


VSAM Logic 


M VS/ Extended A rchitecture 
VSAM Logic 


LY26-3970 


31-Bit 
Addressing 


M VS/ Extended A rchitecture 
System Programming Library: 
3 1 -Bit Addressing 


GC28-1158 



Notational Conventions 



A uniform system of notation describes the format of VSAM macro instructions. 
This notation is not part of the language; it merely provides a basis for describing 
the structure of the macros. 

The macro format illustrations in this book use the following conventions: 

• Brackets [ ] indicate optional parameters. 

• Braces { } indicate a choice of entry; unless a default is indicated, you must 
choose one of the entries. 

• Items separated by a vertical bar (|) represent alternative items. No more 
than one of the items may be selected. 
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• An ellipsis (...) indicates that multiple entries of the type immediately 
preceding the ellipsis are allowed. 

• Other punctuation (parentheses, commas, etc.) must be entered as shown. 

• BOLDFACE type indicates the exact characters to be entered. Such items 
must be entered exactly as illustrated (in uppercase, except in TSO). 

• Italics type specifies fields to be supplied by the user. 

• BOLDFACE-UNDERSCORED type indicates a default option. If the 
parameter is omitted, the underscored boldface value is assumed. 

• A ' ' in the macro format indicates that a blank (an empty space) must be 
present before the next parameter. 
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Summary of Changes 



Release 3.0, June 1987 



| New Programming Support 



• A new parameter, MODE= 24J31, has been added to the BLDVRP, 
CLOSE, DLVRP and OPEN macros. 

• A new parameter, RMODE31 = (ALL|BUFF|CB|NONE), has been added to 
the ACB, BLDVRP, GENCB and MODCB macros. This new parameter 
replaces the MACRF = AMODE31 subparamctcr in the ACB, 
GENCB-ACB, and MODCB-ACB macros and the LOC parameter in the 
BLDVRP and GENCB-RPL macros. 

• A new specification, DATA|INDEX, has been added to the TYPE parameter 
in the BLDVRP macro. 

• A new option, LDS, has been added to the TESTCB-ACB macro. 

• The parameter LOC = BELOW|ANY has been added to the GENCB macro. 

• The BLDVRP, CLOSE, DLVRP, and OPEN parameter lists, the ACB, and 
other control blocks and I/O buffers may now reside above or below 16 
megabytes. 

• New codes have been added to the logical error reason codes in the feedback 
field of the request parameter list. 

• New codes have been added to the return codes from BLDVRP and some 
existing code descriptions have been changed. 

• Some code descriptions have been changed in the open reason codes in the 
error field of the access method control block. 



Summary of Changes IX 



Service Changes 

Information has been added to reflect technical service changes. 



Version 2 Publications 



The tables containing the macro operand expressions in Appendix C, "Operand 
Notation" have been deleted. 



Release 2.0, June 1986 

Service Changes 

Information has been added to reflect technical service changes. 

Version 2 Publications 

The preface has been updated to include order numbers, foe Version 2. 



Release 1.0, April 1985 



A new parameter, ACTION = REFRESH, has been added to the VERIFY 
macro. 

A new parameter, IOPID, has been added to the EXLST macro. This parameter 
permits termination of existing I/O and prevention of new I/O. 
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Chapter 1. Macro Instruction Return Codes and Reason Codes 



This chapter describes the return codes and reason codes generated by the macro 
instructions used to open and close a data set, manage VSAM control blocks, 
and issue data processing requests. 

VSAM sets the return codes in register 15. These return codes are paired with 
reason codes set in the access method control block (ACB) and the request 
parameter list (RPL). Reason codes set in the ACB indicate open or close errors. 
Reason codes set in the RPL indicate record management errors. 

This manual lists return codes and reason codes in decimal and hexadecimal 
values. The decimal value is shown first, followed by the hexadecimal value in 
parentheses. Format descriptions and examples of each macro are shown in 
Chapter 2, "VSAM Macro Formats and Examples" on page 33. 



Return Codes and Reason Codes from OPEN 

When your program receives control after issuing an OPEN macro, the return 
code in register 15 indicates whether all of the VSAM data sets were opened 
successfully: 

Return 

Code Condition 

0(0) All data sets were opened successfully. 

4(4) All data sets were opened successfully, but one or more warning 

messages were issued (reason codes less than X'80'). 

8(8) At least one data set (VSAM or non-VSAM) was not opened 

successfully; the access method control block was restored to the 
contents it had before OPEN was issued; or, if the data set was 
already open, the access method control block remains open and 
usable and is not changed. 

12(C) A non-VSAM data set was not opened successfully when a 

non-VSAM and a VSAM data set were being opened at the same 
time; the non-VSAM data control block was not restored to the 
contents it had before OPEN was issued (and the data set cannot be 
opened without restoring the control block). 
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If register 15 contains a nonzero return code, you can use the SHOWCB macro 
to display the corresponding reason code. The SHOWCB macro displays the 
error field in each access method control block specified by the OPEN macro. 
(See "SHOWCB Macro (Display Fields of an Access Method Control Block)" 
on page 133.) Figure 1 lists the reason codes that may appear in this error field. 
VSAM also writes a message to the operator console and to the programmer's 
listing to explain the error further. For a listing of VSAM messages, see System 
Messages. 



Reason 
Code 

0(0) 



76(4C) 

92(5C) 

96(60) 
100(64) 

104(68) 

108(6C) 
116(74) 



118(76) 



Condition 

One of the following conditions exists: 

• VSAM is processing the access method control block for some 
other request. 

• The access method control block address is invalid. 

Warning message: The interrupt recognition flag (IRF) was detected 
for a data set opened for input processing. 

Warning message: Inconsistent use of CBUF processing. Sharing 
options, differ between index anddata. components. 

Warning message: An unusable data set was opened for input. 

Warning message: OPEN encountered an empty alternate index that 
is part of an upgrade set. 

Warning message: The time stamp of the volume on which a data set 
is stored docsn t match the system time stamp in the data set's catalog 
record; this indicates that extent information in the catalog record 
may not agree with the extents indicated in the volume's VTOC. 

Warning message: The time stamps of a data component and an 
index component do not match; this indicates that cither the data or 
the index has been updated separately from the other. 

Warning message: The data set was not properly closed and cither 
OPEN's implicit verify was unsuccessful or the user specified that 
OPEN's implicit verify should not be executed. 

A previous VSAM program may have abnormally terminated. Data 
may be lost if processing continues; the access method services 
VERIFY command may be used to cause the data set to be properly 
closed. For a description of the VERIFY command, see Access 
Method Services Reference. In a cross-system shared DASD 
environment, a return code of 1 16 can have two meanings: (1) the 
data set was not properly closed, or (2) the data set is opened for 
output on another processor. 

Warning message: The data set was not properly closed but OPEN's 
implicit verify was successfully executed. 



Figure 1 (Part I of 4). OPEN Reason Codes in the ERROR Field of the Access 
Method Control Block 
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Reason 
Code 



Condition 



128(80) 
132(84) 



136(88) 

140(8C) 
144(90) 

145(91) 

148(94) 



DD statement for this access method control block is missing or 
invalid. 

One of the following errors occurred: 



Not enough storage was available for work areas. 

The required volume could not be mounted. 

An uncorrectable I/O error occurred while VSAM was reading 

the job file control block (JFCB). 

The format- 1 DSCB or the catalog cluster record is invalid. 

The user-supplied catalog name does not match the name on the 

entry. 

The user is not authorized to open the catalog as a catalog. 



Not enough virtual storage space is available in your program's 
address space for work areas, control blocks, or buffers. 

The catalog indicates this data set has an invalid physical record size. 

An uncorrectable I/O error occurred while VSAM was reading or 
writing a catalog record. 

An uncorrectable error occurred in the VSAM volume data set 
(WDS). 

No record for the data set to be opened was found in the available 
catalog(s), or an unidentified error occurred while VSAM was 
searching the catalog. For the catalog return code, see system 
message IDC3009I in System Messages. 



1 52(98) Authorization checking has failed for the following reasons: 

1. The password specified in the access method control block for a 
specified level of access doesn't match the password in the catalog 
for that level of access. 

2. RACF failure. For the catalog return code, see system message 
IDC3009I in System Messages. 

160(A0) The operands specified in the ACB or GENCB macro are 

inconsistent cither with each other or with the information in the 
catalog record. 

One of these conditions has been detected: 

• For option ACBRST 

- Path processing 

- LSR|GSR 

• For option ACBICI 

- LSR|GSR 

- KSDS 

Figure 1 (Part 2 of 4). OPEN Reason Codes in the ERROR Field of the Access 
Method Control Block 
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Reason 
Code 



Condition 



164(A4) 



— Path processing 

— Sequence set with data 

— Replicated index 

— Blocksizc not equal to CI size 

• For option ACBUBF 

— LSR|GSR 

— ACBCNV not specified 

— ACBKEY specified 

— ACBADR specified 

• For option ACBSDS 

— LSR|GSR 

— Path processing 

— Upgrade processing 

• For option ACBCBIC 

— LSR|GSR 

— ACBICI not specified 

• For miscellaneous options 

— Buffcrspace specified and the amount is too small to process 
the data set 

— Volume not mounted 

— Frying to open an empty data set for input 

An uncorrectable I/O error occurred while VSAM was reading the 
volume label. 



168(A8) The data set was not available for the type of processing you 

specified, or an attempt was made to open a reusable data set with the 
reset option while another user had the data set open. The data set 
may have the INHIBIT attribute specified. 

The data set cannot be opened for CBUF processing because it was 
already opened for non-CBUF processing. Or the data set has 
conflicting CBUF attributes for the data and index components of the 
ACB. 

176(B0) An error occurred while VSAM was attempting to fix a page of 
virtual storage in real storage. 

180(B4) A VSAM catalog specified in JCL either does not exist or is not 

open, and no record for the data set to be opened was found in any 
other catalog. 

184(B8) An uncorrectable I/O error occurred while VSAM was completing an 
I/O request. 

188(BC) The data set indicated by the access method control block is not of 
the type that may be specified by an access method control block. 

192(C0) An unusable data set was opened for output. 

Figure 1 (Part 3 of 4). OPEN Reason Codes in the ERROR Field of the Access 
Method Control Block 
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Reason 
Code 

193(C1) 



196(C4) 
200(C8) 



Condition 

The interrupt recognition flag (IRF) was detected for a data set 
opened for output processing. 

Access to data was requested via an empty path. 

The Format-4 DSCB indicates that the volume is unusable. There 
was an error in CONVERTV to convert the volume from cither real 
to virtual or virtual to real. 



204(CC) The ACB MACRF specification is GSR and caller is not operating in 
supervisor protect key to 7, or ACB MACRF specification is CBIC 
(Control Blocks in Common) and caller is not operating in supervisor 
state with protect key to 7. 

205(CD) The ACBCATX option or VSAM volume data set OPEN was 
specified and the calling program was not authorized. 

208(D0) The ACB MACRF specification is GSR and caller is using an 
OS/VS1 system. 

212(D4) The ACB MACRF specification is GSR or LSR and the data set 
requires load mode processing. 

216(D8) The ACB MACRF specification is GSR or LSR and the key length 
of the data set exceeds the maximum key length specified in 
BLDVRP. 

220(DC) ITic ACB MACRF specification is GSR or LSR and the data set's 
control interval size exceeds the size of the largest buffer specified in 
BLDVRP. 

224(E0) Improved control interval processing is specified and the data set 
requires load mode processing. 

228(E4) The ACB MACRF specification is GSR or LSR and the VSAM 
shared resource table (VSRT) does not exist (no buffer pool is 
available). 

^232(E8) Reset was specified for a nonreusable data set and the data set is not 
empty. 

236(EC) A permanent staging error occurred in MSS (ACQUIRE). 

240(F0) Format-4 DSCB and volume timestamp verification failed during 
volume mount processing for output processing. 

244(F4) The volume containing the catalog recovery area was not mounted 
and not verified for output processing. 

Figure 1 (Part 4 of 4). OPEN Reason Codes in the ERROR Field of the Access 
Method Control Block 
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Return Codes from CLOSE 



When your program receives control after it has issued a CLOSE macro, a return 
code in register 15 indicates whether all the VSAM data sets were closed 
successfully: 

Return 

Code Condition 

0(0) All data sets were closed successfully. 

4(4) At least one data set (VSAM or non-VSAM) was not closed 

successfully. 

If register 15 contains 4, you can use SIIOWCB to display the ERROR field in 
each access method control block to find out whether a VSAM data set wasn't 
closed successfully and why not. (See "SHOWCB Macro (Display Fields of an 
Access Method Control Block)" on page 133.) Figure 2 gives the reason codes 
that the ERROR field may contain following CLOSE. In addition to these 
reason codes, VSAM writes a message to the operator's console and the 
programmer's listing to further explain the error. For a listing of these messages, 
see System Messages. 



Return 

Code Condition 

0(0) No error (set when register 15 contains 0). 

4(4) The data set indicated by the access method control block is already 

closed. 

129(81) TCLOSE was issued against a media manager's structure. 

132(84) An uncorrectable I/O error occurred while VSAM was reading the 
job file control block (JFCB). 

136(88) Not enough virtual storage was available in your program's address 
space for a work area for CLOSE. 

144(90) An uncorrectable I/O error occurred while VSAM was reading or 
writing a catalog record. 

145(91) An uncorrectable error occurred in the VSAM volume data set 
(WDS). 

148(94) An unidentified error occurred while VSAM was searching the 
catalog. 

Figure 2 (Part 1 of 2). CLOSE Reason Codes in the ERROR Field of the Access 
Method Control Block 
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Return 

Code Condition 

184(B8) An uncorrectable I/O error occurred while VSAM was completing 
outstanding I/O requests. 

236(EC) A permanent destaging error occurred in MSS (RELINQUISH). 
With temporary CLOSE, a destaging error or a staging error 
(ACQUIRE) occurred. 

Figure 2 (Part 2 of 2). CLOSE Reason Codes in the ERROR Field of the Access 
Method Control Block 



OPEN/CLOSE Message Area for Multiple Reason or Warning 
Messages 



During the execution of an OPEN, CLOSE, or TYPE = T option of CLOSE, 
more than one error condition may be detected. However, the ACB error flag 
field can only accommodate one warning or error condition. In order to receive 
multiple error or warning conditions, you may specify an optional message area. 
VSAM will accumulate error messages from an OPEN, CLOSE, or TYPE = T 
option in this message area. 

Multiple messages will be supplied when you specify nonzero values in the 
MAREA and MLEN parameters of the ACB. If MAREA or MLEN is not 
specified or is zero, no error or warning information is stored into the message 
area. The ACB error flag field is then the only indication for errors or warnings. 
If MAREA and MLEN are specified andtfthe^message area is too small to 
accommodate all messages, the last incoming messages are dropped. However, 
you will be given an indication of the number of warnings and me sages that 
occurred. 

The message area provided by VSAM is subdivided into two parts: 

• The message area header 

• The message list 



Message Area Header 



The message area header contains statistical, pointer, and general information. Its 
contents are unrelated to the individual messages. The format of the message 
area header is shown in Figure 3 on page 8. 
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ByteO Flag Byte 

bit 0=1 Full message area header has 
been stored. 

bit = Only flag byte of message area 
header has been stored. 
(Implies that no messages 
have been stored.) 

bits 1-7 Reserved (set to binary zeros) 

Bytes 1-2 Length of message area header (includes flag byte 

and length byte) 

Byte 3 Request type code: 

X'Or OPEN 

X'02' CLOSE 

X'03' TCLOSE 

Bytes 4-U ddaame use&fbr ACB 

Bytes 12-13 Total number of messages (error or warning 

conditions) issued by OPEN/CLOSE/ TCLOSE 

Bytes 14-15 Number of messages stored by OPEN/CLOSE/TCLOSE 
into message area 

Bytes 16- 19 Address of message list, for example, of first 
message in message area 

Figure 3. Format of the Message Area I leader 



The function of the ACB error flag field remains unchanged whether or not this 
optional message area is specified. At the end of an OPEN, CLOSE, or 
TCLOSE, this field contains either X f 00 ' (indicating no error or warning 
condition occurred) or a nonzero code. The ACB error flag byte stores the 
nonzero OPEN/CLOSE/TCLOSE reason code corresponding to the error or 
warning condition that occurred with the highest severity. 

Message area header information is only stored when a warning or error 
condition is detected; that is, when the ACB error flag field is set to a nonzero 
value. The header information consists of the flag byte only if the message area 
length (MLEN) is not large enough to accommodate the full message area 
header. In this case, bit of the flag byte will be zero. Before accessing the 
message header information (bytes 1 through 19), test byte to see if more 
information is stored. If MLEN = 0, no header information is stored, not even 
the flag byte. If the full message area header is stored, bytes 1 and 2 contain its 
actual length. Your program should be sensitive to this length when interrogating 
the message area header. 
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Message List 



The message list contains individual messages corresponding to detected warning 
or error conditions. Bytes 16 through 19 of the message area header point to the 
location of the message list within the message area. If the message area header is 
not stored completely (bit of byte is 0), the location of the message list is not 
provided. Within the message list, individual messages are stored as a contiguous 
string of variable-length records. Bytes 14 and 15 of the message area header 
contain the number of messages stored. Check for a nonzero stored message 
count before investigating the message list. However, messages may not be 
stored even if the ACB error flag byte contains a nonzero value and the message 
area header bit of byte is 1. For example, no messages will be stored if 
MLEN is not large enough to allow at least one message to be stored. 

The format of the individual messages is given in Figure 4. 



Bytes 0-1 Length of message including these two bytes. 

Byte 2 ACB error flag code corresponding to the error or warning 

condition represented by this message. 

Byte 3 Function type code: 

Specifies which dsnamc, if any, is stored in bytes 4 through 47 of 
the message. 

X'00' no dsnamc stored. Bytes 4-47 of the message contain 
binary zeros. The error warning condition is not clearly 
related to a component, or VSAM was unable to identify 
or obtain the cluster name of the component in error. 
This code is used only if the ddname of the ACB does not 
identify a valid DD statement, or VSAM was unable to 
obtain the dsname contained in 4he DD statement. 

X'OT dsname contained in DD statement is stored. The error 
or warning condition is not clearly related to a 
component, or VSAM was unable to identify or obtain 
the cluster name of the component in error. 

X'02' dsname (cluster name) of base cluster stored. Error 
occurred during OPEN/CLOSE/TCLOSE for base 
cluster. 

X'03' dsname (cluster name) of alternate index component 

stored. Error occurred during OPEN/CLOSE/TCLOSE 
for alternate index component. 

X'04' dsnamc (cluster name) of member of upgrade set stored. 
Error occurred during OPEN/CLOSE/TCLOSE for this 
member of the upgrade set. 

Bytes 4-47 Binary zeros (function type code = X'OO') or a dsname as described 
by byte 3. 

Figure 4. Format of Individual Messages in Message List 
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Bytes and 1 of each message specify its actual length. Because messages vary in 
length, you will need to know the actual length of each message in order to do 
your processing. 

Byte 2 of the message contains the ACB error flag code; it does not indicate that 
a dsnarne has been stored. Depending on the condition that raised the ACB 
error flag code, either no dsnarne or different types of dsnames (DD, base cluster, 
alternate index, or upgrade set member) may be stored. (The same condition 
may be detected both when opening the base cluster and when opening a 
member of the upgrade set. For example, an I/O error may occur when trying to 
obtain the dsnarne for the component in error.) Bytes 4 through 47 of the 
message can contain a dsnarne, but do not specify its type. Only byte 3 of the 
message specifics whether a dsnarne has been stored and, if so, its type. 



Control Block Manipulation Macro Return Codes and Reason Codes 

The GENCB, MODCB, SHOWCB, and TESTCB macros are executable (unlike 
the ACB, EXLST, and RPL macros). They cause control to be given to VSAM 
to perform the indicated task. VSAM indicates if the task was completed by a 
return code in register 15: 

Return 

Code Condition 

0(0) Task completed. 

""" ""■""• 4(4) Task not completed. 

8(8) An attempt was made to use the execute form of a macro to modify a 

keyword that isn't in the parameter list. (See Appendix B, "List, 
Execute, and Generate Forms of Macros" on page 171.) 

An error can occur because you specified the operands incorrectly or, if you 
constructed a parameter list yourself, because the parameter list was coded 
incorrectly. See Appendix D, "Building Parameter Lists" on page 183, for an 
explanation of how to construct parameter lists for GENCB, MODCB, 
SHOWCB, and TESTCB. 

When wgBter*r5^atam»'4HggatcrflT^^ 

U&^ft6tircfft^prrforak thti Usk-^y" you construct the parameter list, register 
can contain reason codes 1, 2, 3, 10, 14, 20, and 21. Figure 5 on page 1 1 
describes each reason code that can be returned in register 0. 
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Reason 
Code 


Applicable 
Macros 1 


KD 


G,M,S,T 


2(2) 


G,M,S,T 


3(3) 


G,M,S,T 


4(4) 


M.S.T 



Reason VSAM Couldn't Perform the Task 

The request type (generate, modify, show, or test) is 
invalid. 

The block type (access method control block, exit list, or 
request parameter list) is invalid. 

One of the keyword codes in the parameter list is invalid. 

The block at the address indicated is not of the type you 
indicated (access method control block, exit list, or request 
parameter list). 

5(5) S,T — ^ Access method control block fields were to be shown or 
tested, but the data set is not open or it is not a VSAM 
data set. 

6(6) S,T Access method control block information about an index 

was to be shown or tested, but no index was opened with 
the data set. 

7(7) M,S An exit list was to be modified, but the list was not large 

enough to contain the new entry; or an exit was to be 
modified or shown but the specified exit wasn't in the exit 
list. (With TESTCB, if the specified exit address isn't 
present, you get an unequal condition when you test for 
it.) 

8(8) G There isn't enough virtual storage in your program's 

address space to generate the access method control 
block(s), exit list(s), or request parameter list(s) and no 
work area outside your address space was specified. 

9{9) <£ ,S Tfee work area specified was too small for generation <?r 

display of the indicated control block or fields. 

10(A) G,M With GENCB, exit list control block type was specified 

and you specified an exit without without giving an 
address. With MODCB, exit list control block type was 
specified and you specified an exit without giving an 
address; in this case, either active or inactive must be 
specified, but load cannot be specified. 

1 1(B) M Either (1) a request parameter list was to be modified, but 

the request parameter list defines an asynchronous request 
that is active (that is, no CHECK or ENDREQ has been 
issued on the request) and thus cannot be modified; or (2) 
MODCB is already issued for the control block, but 
hasn't yet completed. 



Figure 5 (Part 1 of 2). GENCB, MODCB, SHOWCB, and TESTCB Reason Codes 
Returned in Register 
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Reason Applicable 

Code Macros 1 Reason VSAM Couldn't Perforin the Task 

12(C) M An access method control block was to be modified, but 

the data set identified by the access method control block 
is open and thus cannot be modified. 

13(D) M An exit list was to be modified, and you attempted to 

activate an exit without providing a new exit address. 
Because the exit list indicated docs not contain an address 
for that exit, your request cannot be honored. 

14(E) G,M,T One of the option codes (for MACRF, ATRB, or 

OPTCD) has an invalid combination of option codes 
specified (for example, OPTCD = (ADR, SKP)). 

15(F) G,S The work area specified did not begin on a fullword 

boundary. 

16(10) G,M,S,T A VTAM keyword or subparameter was specified but the 
AM = VTAM parameter was not specified. AM = VTAM 
must be specified in order to process a VTAM version of 
the control block. 

L9( 13} M,S?T A, keyword was- specified which refers to a field beyond 

the length of the control block located at the address 
indicated. (For example, a VTAM keyword was specified, 
but the control block pointed to was a shorter, 
non-VTAM block.) 

20(14) S Keywords were specified which apply only if 

MACRF = LSR or GSR. 

21(15) S,T The block to be displayed or tested does not exist because 

the data set is a dummy data set. 

22(16) S AM = VTAM was specified and the RPL FIELDS 

parameter conflicts with the RPLNIB bit status. Either 
RPLFIELDS = NIB was specified and the RPLNIB was 
ofT, or RPL FIELDS = ARG was specified and the 
RPLNIB bit was on. 



Figure 5 (Part 2 of 2). GENCB, MODCB, SIIOVVCB, and TESTCB Reason Codes 
Returned in Register 

Note to Figure 5: 

1 G = GENCB, M = MODCB, S = SIIOWCB, T=TESTCB 
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Record Management Return Codes and Reason Codes 



The following record management macros give return codes and reason codes in 
the feedback area of the RPL: GET, PUT, POINT, ERASE, CHECK, 
ENDREQ, GETIX, PUTIX, ACQRANGE, CNVTAD, MNTACQ, 
MRKBFR, SCHBFR, and WRTBFR. 

The feedback word in the RPL consists of four bytes: 

Byte Description 

1 Problem determination function (PDF) code. This code is used to locate 
the point in VSAM record management at which a logical error 
condition is recognized. A description of the returned PDF code is 
located in the IDARMRCD macro. 

2 RPL return code. This code is returned in register 15. 

3 Component code. This code specifies the component being processed 
when the error occurred. 

4 Reason code. This code, when paired with the return code in byte 2, 
specifics the actual reason for cither a successful completion or an error. 

Bytes 2 through 4 make up the RPL feedback area. An explanation of the codes 
that appear in these three bytes follows. 

Bytes 3 and 4 make up the RPL condition code. An explanation of this code 
also follows. 

The field name of each byte appears within parentheses in the following figure. 



RPL Feedba ck Word (<♦ bytes) 



RPL Feedbac k Area (3 bytes) 



RPL Condition Code (2 bytes) 



PDF Code 
(RPLFUNCD) 



Return Code 
(RPLRTNCD) 



Component Code 
(RPLCMPON) 



Reason Code 
(RPLERRCD) 



For more information on the RPL feedback word, see VSAM Logic. 



Return Codes (RPLRTNCD) 



The meaning of the return code depends on whether processing is asynchronous 
or synchronous. 
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Asynchronous Request 



Synchronous Request 



After you issue an asynchronous request for access to a data set, VSAM issues a 
return code in register 15 to indicate whether the request was accepted, as follows: 



Return Code 
(RPLRTNCD) 

0(0) 

4(4) 



Condition 



Request was accepted. 



Request was not accepted because the request parameter list 
indicated by the request (RPL= address) was active for another 
request. 



If the asynchronous request was accepted, issue a CHECK after doing your other 
processing so VSAM can indicate in register 15 whether the request was 
completed successfully, set a return code in the feedback area, and exit to any 
appropriate exit routine. If the request was not accepted, you should either wait 
until the other request is complete (for example, by issuing a CHECK on the 
request parameter list) or terminate the other request (using ENDREQ). Then 
you can reissue the rejected request. 



After a synchronous request, or a CHECK or ENDREQ macro, the return code 
in register 15 indicates whether the request was completed successfully, as follows: 

Return Code 
(RPLRTNCD) Condition 



0(0) 
4(4) 

8(8) 
12(C) 



Request completed successfully. 

Request was not accepted because the request parameter list 
indicated by the request (R PL = address) was active for another 
request. 

Logical error; specific error is indicated in the feedback area in 
the RPL. 

Physical error; specific error is indicated in the feedback area in 
the RPL. 



Component Codes (RPLCMPON) 



When a logical or physical error occurs, VSAM uses the component code field of 
the RPL to identify the component being processed when the error occurred and 
indicates whether the alternate index upgrade set is correct following the request 
that failed. The component code can be displayed and tested by using the 
SHOWCB and TESTCB macros. The codes and their meanings are given in 
Figure 6 on page 15. 
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Note: The component code (byte 3 of the RPL feedback word) and the reason 
code (byte 4 of the RPL feedback word) make up the 2-byte RPL condition 
code. 

For more information on the RPL feedback word see VSAM Logic. 



Component Code 
(RPLCMPON) 


What Was Iking 
Processed 


Upgrade Set Status 


0(0) 


Base cluster 


Correct 


1(1) 


Base cluster 


May be incorrect 


2(2) 


Alternate index 


Correct 


3(3) 


Alternate index 


May be incorrect 


4(4) 


Upgrade set 


Correct 


5(5) 


Upgrade set 


May be incorrect 



Figure 6. Component Codes Provided ht the RPL 



Reason Codes (RPLERRCD) 



The 0, 8, and 12 return codes in register 15 are paired with reason codes in the 
feedback area of the request parameter list. 

The reason codes in the feedback area of the request parameter list can be 
examined with the SHOWCB or TESTCB macro. You may code your 
examination routine immediately following the request macro. Logical errors, 
physical errors, *nd reaching the end of the data set aM cause VSAM to ton to 
the appropriate exit routine, if you provide one. 

Coordinate error checking in your program with your error-analysis exit routines. 
If they terminate the program, for instance, you would not need to code a check 
for an error after a request. But if a routine returns to VSAM to continue 
processing, you should check register 15 after a request to determine whether 
there was an error. Even though the error was handled by an exit routine, you 
may want to modify processing because of the error. 



Reason Code (Successful Request) 



When the request is completed, register 15 is set to indicate the status of the 
request. A reason code of indicates successful completion. Nonzero codes are 
set for a variety of other reasons. Figure 7 on page 16 lists these codes and their 
meanings. 
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Reason Code 

(RPLERRCD) 

When Register 

15 = 0(0) Condition 

0(0) Request completed successfully. 

4(4) Request completed successfully. For retrieval, VSAM mounted 

another volume to locate the record; for storage, VSAM allocated 
additional space or mounted another volume. 

8(8) For GET requests, indicates a duplicate alternate key exists 

(appUes only when accessing a data set using an alternate index 
that allows nonunique keys); for PUT requests, indicates that a 
duplicate key was created in an alternate index with the 
nonunique attribute. 

12(C) All buffers, except for the buffer just obtained, may have been 

modified and may need to be written; issuance of WRTBFR 
macro is suggested. 

16(10) The sequence-set record does not have enough space to allow it 

to address all of the control intervals in the control area that 
should contain the record. The record was written into a new 
control area. 

20(14) Data set is not on virtual DASD for 

CNVTAD/MNTACQ/ACQRANGE request. 

24(18) Buffer found but not modified; no buffer writes performed. 

28(1 C) Control interval split indicator was detected during an addressed 

GET NUP request. 

32(20) Request deferred for a resource held by the terminated RPL is 

asynchronous and cannot be restarted by TERMRPL. 

36(24) Possible data set error condition was detected by TERMRPL: 

• The request was abnormally terminated in the middle of its 
I/O operation. 

• One of the data/index BUFCs of the string contains data that 
needs to be written (BUFCMW=ON) but it was invalidated 
by TERMRPL. 

40(28) Error in PLH data BUFC pointer was detected by TERMRPL. 

Figure 7. Successful Completion Reason Codes in the Feedback Area of the Request 
Parameter List 
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Reason Code (Logical Errors) 



If a logical error occurs and you have no LERAD routine (or the LERAD exit is 
inactive), VSAM returns control to your program following the last executed 
instruction. ("User-Written-Exit Routines" in Data Facility Product: 
Customization describes the LERAD routine.) The return code in register 1 5 
indicates a logical error (8), and the feedback area in the request parameter list 
contains a reason code identifying the error. Register 1 points to the request 
parameter list. 

Figure 8 gives the reason codes shown in the feedback area and explains their 
meanings. 



Reason Code 

(RPLERRCD) 

When Register 

15 = 8(8) Condition 

4(4) End of data set encountered (during sequential or 

skip sequential retrieval), or the search argument 
is greater than the high key of the data set. 
Either no EODAD routine is provided, or one is 
provided, returned to VSAM, and the processing 
program issued another GET. ("User-Written-Exit 
Routines" in VSAM Administration Guide describes 
the EODAD routine.) 

.W 8(8) You attempted to store a record with a duplicate 

* key, or there is a duplicate record for an 

alternate index with the unique key option. 

12(C) A key sequence check was performed and an error was 

detected in one of the following processing 
conditions: 

* For-a lcey-scqucnced data set 

— PUT sequential or skip-sequential processing 

— GET sequential, single string input only 

— GET skip-sequential processing and the previous 
request is not a POINT 

• For a relative record data set 

— GET skip-sequential processing 

— PUT skip-sequential processing 

16(10) Record not found, or 

the RBA is not found in the buffer pool. 

Figure 8 (Part I of 7). Logical Error Reason Codes in the Feedback Area or the 
Request Parameter List 
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Reason Code 

(RPLERRCD) 

When Register 

15 = 8(8) Condition 

20(14) The RBA is found, but the buffer is under the exclusive control of 

another request. With this condition, it is possible to also have 
buffers invalidated. Or, the control interval is for a record already 
held in exclusive control by another requester. 

Note: If the RPL message area is correctly specified, the following 
information is returned: 

OfTsct Length Discussion 

4 Address of RPL in exclusive 

control 

4 1 Flag Byte: 

X * 00 ' - neither R PL is doing a 
control area split 

X * 01 ' - current RPL is attempting a 
control area sput 

X ' 02 ' - other RPL is doing 
a control area split 

24(18) Record resides on a volume that can't be mounted. 

28(IC) Data set cannot be extended because VSAM can't allocate 

additional direct access storage space. Either there is not enough 
space left to make the secondary allocation request or you 
attempted to increase the size of a data set while processing with 
SHAREOPTIONS = 4and DISP = SHR. 

32(20) You specified an RBA that doesn't give the address of any data 

record in the data set. 

36(24) Key ranges were specified for the data set when it was defined, but 

no range was specified that includes the record to be inserted. 

40(28) Insufficient virtual storage in your address space to complete the 

request. 

44(2C) Work area not large enough for the data record or for the buffer 

(GET with OPTCD = MVE). 

Figure 8 (Part 2 of 7). Logical Error Reason Codes in the Feedback Area of the 
Request Parameter List 
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Reason Code 
(RPLERRCD) 
When Register 
15=8(8) Condition 



48(30) 



52(34) 
64(40) 

68(44) 
72(48) 
76(4C) 
80(50) 



84(54) 



Invalid options, data set attributes, or processing conditions 
specified for TERMRPL request: 

CNV processing 

The specified RPL is asynchronous 

Chained RPLs 

Path processing 

Shared resources (LSR/GSR) 

Load mode 

Relative record data set 

Data set contains spanned records 

User not in key and supervisor state 

End-of-volume in process (secondary allocation) 

The previous request was TERMRPL. 

There is insufficient storage available to dynamically add another 
string. Or, the maximum number of placeholders that may be 
allocated to the request has been allocated, and a placeholder is not 
available. 

You attempted to use a type of processing (output or control 
interval processing) that was not specified when the data set was 
opened. 

You made a keyed request for access to an entry-scquenced data 
set, or you issued a GETIX or PUTIX to an entry-sequenced or 
relative record data set. 

You issued an addressed or control "interval PUT to add to a 
key-sequenced data set, or you issued a control interval PUT to a 
relative record data set. 

You issued an ERASE request in one of the following situations: 

• For access to an entry-sequenced data set. 

• For access to an entry-sequenced data set via a path. 

• With control interval access. 

You specified OPTCD = LOC in one of the following situations: 

• For a PUT request. 

• In a request parameter list in a chain of request parameter lists. 

• For UBF processing. 

Figure 8 (Part 3 of 7). Logical Error Reason Codes in the Feedback Area of the 
Request Parameter List 
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Reason Code 
(RPLERRCD) 
When Register 
15=8(8) Condition 



88(58J You issued a sequential GET request without having caused 

w VSAM to be positioned for it, or you changed from addressed 

access to keyed access without causing VSAM to be positioned for 
keyed-sequential retrieval; there was no positioning established for 
sequential PUT insert for a relative record data set, or you 
attempted an illegal switch between forward and backward 
processing. 

92(5C) You issued a PUT for update or an ERASE without a previous 

GET for update, or a PUTIX without a previous GETIX. 

96(60) You attempted to change the prime key or key of reference while 

making an update. 

100(64) You attempted to change the length of a record while making an 

addressed update. 

104(68) The RPL options are either invalid or conflicting in one of the 

following, ways: 

• SKP was specified and either KEY was not specified or BWD 
was specified. 

• BWD was specified for CNV processing. 

• FWD and LRD were specified. 

• Neither ADR, CNV, nor KEY was specified in the RPL. 

• BFRNO is invalid (less than 1 or greater than the number of 
buffers in the pool). 

• WRTBFR, MRKBFR, or SCHBFR was issued, but either 
TRANSID was greater than 31 or the shared resource option 
was not specified. 

• ICI processing was specified, but a request other than a GET 
or a PUT was issued. 

• MRKBFR MARK = OUT or MARK= RLS was issued but 
the RPL did not have a data buffer associated with it. 

• The RPL specified WAITX, but the ACB did not specify LSR 
or GSR. 

Figure 8 (Part 4 of 7). Logical Error Reason Codes in the Feedback Area of the 
Request Parameter List 
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Reason Code 

(RPLERRCD) 

When Register 

15 = 8(8) Condition 

108(6C) RECLEN specified was larger than the maximum allowed, equal to 

0, or smaller than the sum of the length and the displacement of 
the key field; RECLEN was not equal to record (slot) size specified 
for a relative record data set. The automatic increase in the record 
size of an upgrade index for the base cluster may cause an incorrect 
RECLEN specification. 

1 12(70) KEYLEN specified was too large or equal to 0. 

1 16(74) During initial data set loading (that is, when records arc being 

stored in the data set the first time it's opened), GET, POINT, 
ERASE, direct PUT, skip-sequential PUT, or PUT with 
OPTCD= UPD is not allowed. For initial loading of a relative 
record data set, the request was other than a PUT insert. 

120(78) The request was operating under an incorrect TCB. For example, 

an end-of- volume call or a GETMAIN would have been necessary 
to complete the request, but the request was issued from a job step 
other than the one that opened the data set. The request can be 
resubmitted from the correct task, if the new request reestablishes 
positioning. 

124(7C) A request was cancelled for a user JRNAD exit. 

132(84) An attempt was made in locate mode to retrieve a spanned record. 

136(88) You attempted an addressed GET of a spanned record in a 

kcy-sequenccd data set. 

140(8C) The spanned record segment update number is inconsistent. 

144(90) Invalid pointer (no associated base record) in an alternate index. 

148(94) The maximum number of pointers in the alternate index has been 

exceeded. 

152(98) Not enough buffers are available to process your request (shared 

resources only). 

156(9C) An invalid control interval was detected during keyed processing, or 

an addressed GET UPD request failed because the control interval 
flag was on, or an invalid control interval or index record was 
detected. The RPL contains the invalid control interval's RBA. 

Figure 8 (Part 5 of 7). Logical Error Reason Codes in the Feedback Area of the 
Request Parameter List 
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Reason Code 

(RPLERRCD) 

When Register 

15 = 8(8) Condition 

160(A0) One or more candidates were found that have a modified buffer 

marked to be written. The buffer was left in write status with valid 
contents. With this condition, it is possible to have other buffers 
invalidated or found under exclusive control. 

164(A4) One of the following invalid options was specified for a 
CNVTAD/MNTACQ/ACQRANGE request: 

Generic key (GEN) 

Load mode 

Path processing 

User buffers (UBF) with LSR/GSR 

Key-sequenced data set, but not key processing (KEY) 

Entry-scquenced data set, but not address processing (ADR) 

Relative record data set, but not key processing (KEY) 

RPL is chained 

Key-sequenced data set has single-level imbedded index 

168(A8) One of the following user parameter list errors was detected for 

CNVTAD/MNTACQ/ACQRANGE request: 

• No user parameter list is specified (RPLARG = 0) 

• Argument count is zero for CNVTAD/MNTACQ request 

• Ending argument is less than starting argument for 
ACQRANGE request 

• Parameter list not on word boundary 

i72(AC) ACQUIRE error returned by SVC 126 for 
MNTACQ/ACQRANGE request. 

176(B0) Staging failure for MNTACQ/ACQRANGE request. 

180(B4) RBA/volumc error for MNTACQ/ACQRANGE request. 

(Required volume not mounted or specified RBA(s) not on 
mounted volume.) 

Figure 8 (Part 6 of 7). Logical Error Reason Codes in the Feedback Area of the 
Request Parameter List 
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Reason Code 

(RPLERRCD) 

When Register 

15 = 8(8) Condition 

184(B8) Catalog errors returned from SVC 126 for CNVTAD request. 

188(BC) Storage for ACQUIRE ECBs (subpool 241) is not available. 

192(C0) Invalid relative record number. 

196(C4) You issued an addressed request to a relative record data set. 

200(C8) You attempted addressed or control interval access through a path. 

204(CC) PUT insert requests are not allowed in backward mode. 

208(D0) The user has issued an ENDREQ macro instruction against an 
RPL that has an outstanding WAIT against the ECB associated 
with the RPL. This can occur when an ENDREQ is issued from a 
STAE or ESTAE routine routine against an RPL that was started 
before the abend. No ENDREQ processing has been done. 

212(D4) During control area split processing, a condition exists that prevents 

the split of the index record. Index control interval size may need 
to be increased. 

224(E0) MRKBFR OUT was issued for a buffer with invalid contents. 

228(E4) Caller in cross-memory mode is not in supervisor state or RPL of 

caller in SRB or cross-memory mode docs not specify SYN 
processing. 

232(E8) UPAD error; ECB was not posted by user in cross-memory mode. 

236(EC) Validity check error for SHAREOPTIONS 3 or 4. 

240(F0) For shared resources, one of the following is being performed: (a) 

an attempt is being made to obtain a buffer in exclusive control, (b) 
a buffer is being invalidated, or (c) the buffer use chain is changing. 
For more detailed feedback, reissue the request. 

244(F4) Register 14 stack size is not large enough. 

248(F8) Register 14 return offset went negative. 

252(FC) Record mode processing is not allowed for a linear data set. 

253(FD) VERIFY is not a valid function for a linear data set. 

Figure 8 (Part 7 or 7). Logical Error Reason Codes in the Feedback Area of the 
Request Parameter List 
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When the search argument you supply for a POINT or GET request is greater 
than the highest key in the data set, the reason code in the feedback area depends 
on the RPL's OPTGD values, as shown in the table below: 



Request 


RPLs OPTCD 


Reason Code (RPLERRCD) 


Type 


Options 


When Register 15=8(8) 






Decimal 


Hexadecimal 


POINT 


GEN f KEQ 


16 


X f 10' 


POINT 


GEN,KGE 


4 


X'4» 


POINT 


FKS.KEQ 


16 


X'lO* 


POINT 


FKS.KGE 


4 


X'4* 


GET 


GEN.KEQ.DIR 


16 


X'lO* 


GET 


GEN,KGE,DIR 


16 


X'10 1 


GET 


FKS.KEQ.DIR 


16 


X'lO' 


GET 


FKS,KGE,DIR 


16 


X'lO* 


GET 


GEN,KEQ,SKP 


16 


X'lO* 


GET 


GEN.KGE.SKP 


4 


X'4' 


GET 


FKS.KEQ.SKP 


16 


X'lO 1 


GET 


FKS,KGE,SKP 


4 


X'4' 



Positioning Following Logical Errors. 

VSAM is unable to maintain positioning after every logical error. Whenever 
positioning is not maintained following an error request, you must reestablish it 
before processing resumes. 

Positioning may be in one of four states following a POINT or a direct request 
that encountered a logical erron 

Yes VSAM is positioned at the position in effect before the request in error 
was issued. 

No VSAM is not positioned, because no positioning was established at the 
time the request in error was issued. 

New VSAM is positioned at a new position. 

U VSAM is positioned at an unpredictable position. 

The following table shows which positioning state applies to each reason code 
listed for sequential, direct, and skip-sequential processing. "N/A ,f indicates that 
the reason code is not applicable to the type of processing indicated. Figure 9 on 
page 25 lists these codes and their meanings. 
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Reason Code 


(RPLERRCD) 

When Register 

15 = 8(8) 

Decimal Hexadecimal 


4 


XV 


8 


X'8' 1 


12 


x'c* 


16 


X f 10' 


20 


XM4 f 


24 


X'\S' 


28 


X'lC 


32 


X'20 f 


36 


X*24 f 


40 


X'28 f 


44 


X'2C f 


64 


X'40' 


68 


X*44 T 


72 


X'48* 


76 


X'4C f 


80 


X f 50* 


84 


X'54 f 


88 


X*58 f 


92 


X'SC* 


96 


X*60 f 


100 


X f 64* 


104 


x^s' 


108 


X^C' 


112 


X ? 70 f 


116 


X'74' 


120 


X^' 


124 


X*7C f 


132 


X^' 


136 


X f 88 f 


140 


X^C* 


144 


X f 90 ? 


148 


X f 94 f 


152 


X f 98* 


156 


X'9C f 


160 


X'AO* 


192 


X'CO* 


196 


X f C4 f 



Sequential Direct Skip-Sequential 



Yes 


N/A 


Yes 


Yes 


No 


New 


Yes 


N/A 


Yes 


No 


No 


No 


U 


No 2 


No 2 


Yes 


No 


No 


Yes 


No 


Yes 


No 


No 


N/A 


Yes 


No 


New 


Yes 


No 


No 


Yes 


New 


Yes 


No 


No 


No 


Yes 


Yes 


Yes 


Yes 


Yes 


Yes 


Yes 


Yes 


Yes 


Yes 


Yes 


Yes 


Yes 


Yes 


Yes 


Yes 


Yes 


Yes 


Yes 


Yes 


Yes 


Yes 


Yes 


Yes 


Yes 


Yes 


Yes 


Yes 


New 


Yes 


Yes 


New 


Yes 


Yes 


Yes 


Yes 


Yes 


Yes 


Yss 


Yes 


No 


No 


No 


No 


No 


Yes 


New 


Yes 


No 


No 


N/A 


Yes 


New 


Yes 


Yes 


Yes 


Yes 


Yes 


Yes 


Yes 


Yes 


No 


No 


Yes 


No 


No 


N/A 


No 


N/A 


Yes 


Yes 


Yes 


Yes 


Yes 


Yes 



Figure 9 (Part 1 of 2). Positioning States of Reason Codes Listed for Sequential, 
Direct, and Skip-Sequential Processing 
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Reason Code 


(RPLERRCD) 


When Register 


15-8(8) 




Decimal 


Hexadecimal 


200 


x'cs* 


204 


X T CC' 


208 


X f D0 f 


224 


X f E0 f 


228 


X , E4 f 


232 


X'E8* 


236 


X'EC* 


240 


X'FO* 



Sequential Direct Skip-Sequential 



Yes 


Yes 


Yes 


Yes 


Yes 


Yes 


Yes 


Yes 


Yes 


N/A 


No 


N/A 


No 


No 


No 


No 


No 


No 


No 


No 


No 


Yes 


Yes 


Yes 



1 A subsequent GET SEQ will retrieve the duplicate record; however, a 
subsequent GET SKP for the same key will get a sequence error. In a 
relative record data set, a subsequent PUT SEQ positions to the next slot 
(whether the slot is empty or not). 

2 PUT UPD, DIR or UPD, SKP retains positioning. The RPL contains an 
RBA that could not be obtained for exclusive control. 

Figure °* (Part 2 of 2V PosttRfftmf* State* of Reason- GodesLfcrtetJ-forSetfaenttafr, 
Direct, and Skip-Sequential Processing 



Reason Code (Physical Errors) 



If a physical error occurs and you have no SYNAD routine (or the S YNAD exit 
is inactive), VSAM returns control to your program following the last executed 
instruction. The return code in register 15 indicates a physical error (12), and the 
feedback area in the request parameter list contains a reason code identifying the 
error; the RPL message area contains more details about the error. Register 1 
points to the request parameter list. The RBA field in the request parameter list 
gives the relative byte address of the control interval in which the physical error 
occurred. Figure 10 gives the reason codes in the feedback area and explains 
what each indicates. 
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Reason Code 

(RPLERRCD) 

When Register 

15- 12(0C) Condition 

4(4) Read error occurred for a data set. 

8(8) Read error occurred for ail index set. 

12(C) Read error occurred for a sequence set. 

16(10) Write error occurred for a data set. 

20(14) Write error occurred for an index set. 

24(18) Write error occurred for a sequence set. 

Figure 10. Physical Error Reason Codes in the Feedback Area of the Request 
Parameter List 



Figure 1 1 gives the format of a physical error message. The format and some of 
the contents of the message are purposely similar to the format and contents of 
the SYNADAF message, which is described in Data Administration: Macro 
Instruction Reference. 



Field 


Bytes 


Length 


Discussion 


Message 
Length 


0-1 


2 


Binary value of 128 




2-3 


2 


Unused (0) 


Message 
Length - 4 


4-3 


2 


Binary value of 124 
(provided for compatibility 
with SYNADAF Message) 




6-7 


2 


Unused (0) 


Address of 
I/O Buffer 


8-11 


4 


The I/O buffer associated 
with the data where 



the error occurred 
The rest of the message is in printable format 

Date 
Time 
Figure 1 1 (Part 1 of 4). Physical Error Message Format 
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12-16 


5 


YYDDD (year and day) 


17 


1 


Comma (,) 


18-25 


8 


HHMMSSTH (hour, minute, 
second, and tenths and 
hundredths of a second 



Field 


Bytes 


Length 


Discussion 




26 


1 


Comma (,) 


RBA 


27-34 


8 


Relative byte address of the 
record where 
the error occurred 




35 


1 


Comma (,) 


Component 
TYPE 


36-41 
42 


6 
1 


"DATA" or "INDEX" 
Comma (,) 


Volume Serial 
Number 


43-48 


6 


Volume serial number of the 
volume where 
the error occurred 




49 


1 


Comma (,) 


Job Name 


50-57 


8 


Name of the job where 
error occurred 




58 


1 


Comma (,) 


Step Name 


59-66 


8 


Name of the job step in 
which error occurred 




67 


1 


Comma (,) 


Unit 


68-70 


3 


The unit, CUU (channel and 

unit), where 

the error occurred 




71 


1 


Comma (,) 


Device Type 


72-73 


2 


The type of device where 
the error 

occurred (always DA for 
direct access) 




74 


1 


Comma (,) 


ddname 


75-82 


8 


The ddname of the DD 



83 



statement defining the data 
set where the 
error occurred 

Comma (,) 



Figure 1 1 (Part 2 or 4). Physical Error Message Format 
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Field 


Bytes 


Length 


Discussion 


Channel 


84-89 


6 


The channel command that 
caused the error in the first 
two bytes, followed by "_OP" 




90 


1 


Comma (,) 


Message 


91-105 


15 


Messages arc divided 
according to ECB condition 
codes: 



X'4l' "INCORR LENGTH" 
"UNIT EXCEPTION" 
"PROGRAM CHECK" 
"PROTECTION CHK" 
"CHAN DATA CHK" 
"CHAN CTRL CHK" 
"INTFCE CTRL CHK" 
"CHAINING CHK" 
"UNIT CHECK" 

If the type of unit check can 
be determined, the 'UNIT CHECK' 
message is replaced by one of 
by one of the following: 

"CMD REJECT" 
"INT REQ" 
"BUS OUT CK" 
"EQP CHECK" 
"DATA CHECK" 
"OVER RUN" 
"TRACK TX>NDCK" 
"SEEK CHECK" 
"COUNT DATA CHK" 
"TRACK OVERRUN" 
"CYLINDER END" 
"NO RECORD FOUND* 
"FILE PROTECT" 
"MISSING A.M." 
"OVERFL INCP" 

X * 48 ' "PURGED REQUEST* 

X f 4A' "I/O PREVENTED" 

X*4F f "R.HA.RO. ERROR" 

For any other ECB condition code: 

"UNKNOWN COND." 
Figure 1 1 (Part 3 of 4). Physical Error Message Format 
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Field 


Bytes 


Length 


Discussion 




106 


1 


Comma (,) 


Physical 
Direct Access 
Address 


107-120 
121 


14 
1 


BBCCHHR (bin, cylinder, 
head, and record) 

Comma (,) 


Access 
Method 


122-127 


6 


"VSAM" 


Figure 1 1 (Part 4 of 4). Physical Error Message Format 



Return Codes from Macros Used to Share Resources among Data Sets 

VSAM has a set of macros that enables you to share I/O buffers, I/O related 
control blocks, and channel programs among VSAM data sets. 

Return Codes from BLDVRP 

VSAM returns a code in register 15 that indicates whether the BLDVRP request 
was successful: 

Return 

Code Condition 

0(0) VSAM completed the request. 

4(4) The requested data resource pool or index resource pool already exists 

in the address space (LSR) or in the system protect key (GSR). 

8(8) There is not enough virtual storage space to satisfy the request. 

GETMAIN or ESTAE failed. 

12(C) Buffers cannot be fixed in real storage. PAGEFIX failed. 

16(10) TYPE = GSR is specified but the program that issued BLDVRP is 
not in supervisor state with protection key to 7. 

20( 14) STRNO is less than 1 or greater than 255. 

24(18) BUFFERS is specified incorrectly. A size or number is invalid. 

28(1C) The requested resource pool is invalid. A SHRPOOL value greater 
than 15 was specified. 
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32(20) The resource pool already exists above 16 megabytes and the request 
was for storage below 16 megabytes, or the resource pool already 
exists below 16 megabytes and the request was for storage above 16 
megabytes. 

36(24) BLDVRP was issued to build an index resource pool but the required 
corresponding data resource pool does not exist. 



Return Codes from DLVRP 



VSAM returns a code in register 15 that indicates whether the DLVRP request 
was successful: 

Return 

Code Condition 

0(0) VSAM completed the request. 

4(4) There is no resource pool to delete. 

8(8) There is not enough virtual storage space to satisfy the request. 

GETMAIN or ESTAE failed. 

12(C) There is at least one open data set using the resource pool. 

16(10) TYPE = GSR is specified, but the program that issued DLVRP is not 
in supervisor state with protection key to 7. 



Return Codes from End-of-VoIume 



End-of-volume returns the following codes in register 15: 

Return 

Code Condition 

0(0) Successful. 

4(4) The requested volume could not be mounted. 

8(8) The requested amount of space could not be allocated. 

12(C) I/O operations were in progress when end-of- volume was requested. 

16(10) The catalog could not be updated. 
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Chapter 2. VSAM Macro Formats and Examples 



This chapter contains macro instruction formats and examples. 

The macros that work at assembly time allow you to specify subparametcr values 
as absolute numeric expressions, character strings, codes, and expressions that 
generate valid relocatable A-type address constants. The macros that work at 
execution allow you also to specify these values as: 

• Register notation, where the expression designating a register from 2 through 
12 is enclosed in parentheses; for example, (2) and (REG), where REG is a 
label equated to a number from 2 through 12 

• An expression of the form (S.scon), where scon is an expression valid for an 
S-type address constant, including the base-displacement form 

• An expression of the form (*,scon), where scon is an expression valid for an 
S-type address constant, including the base-displacement form, and the 
address specified by scon is indirect— that is, it gives the location of the area 
that contains the value for the subparametcr. 

For most programming applications, you can conveniently use register notation 
or absolute numeric expressions for numbers, character strings for names, and 
register notation or expressions that generate valid A-type address constants for 
addresses. Appendix C, ''Operand Notation" on page 181, fives all the ways of 
coding each parameter for the macros that work at execution time. 

You can write a reentrant program only with execution-time macros. 
Appendix B, "List, Execute, and Generate Forms of Macros" on page 171, 
describes alternative ways of coding these macros for reentrant programs. This 
chapter describes the standard form of these macros. 
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ACB 

ACB Macro (Generate an Access Method Control Block at Assembly 
Time) 

The format of the ACB macro is: 



[label] 


ACB 


|AM = VSAM| 

|,BSTRNO - number] 

|,BUFND = number] 

j,BUFNI = number] 

|,BUFSP- number] 

|,CATALOG = YES|NO| 

|,CRA = SCRA|UCRA| 

|,DDNAME=<fc//?ame| 

|,EXLST = address] 

[,M ACRF - (lADR|f,CNVU,KEYI 

[,CFX|NFX| 

(,DI)N|DSN| 

|,DFR|NDF| 

|,DIR||,SEQH,SKP| 

l,ICI|NCI| 

|,IN||,OUT| 

l,NIS|SISL 

|,NRM|AIX| 

|,NRS|RST| 

|,NSR|LSR|GSRJ 

(,NlJB|tJBF|)| 
|,MAREA = address] 
[,MLEN = number] 
l,PASS\VD = a<fc/re«| 
I.RMODE3I = f ALLIBUFFICBINONE) 1 
f,SHRPOOL= {Q\number}] 
[J&TKNO- number] 



Note: The RMODE31 parameter replaces the AMODE31 subparameter shown 
in previous releases. 



Values for ACB macro subparamcters can be specified as absolute numeri 
expressions, character strings, codes, and expressions that generate valid 
relocatable A-typc address constants. 



label 



is 1 to 8 characters that provide a symbolic address for the access method 
control block that is assembled and also, if you omit the DDNAME 
parameter, serves as the ddname. 

AM = VSAM 

specifies that the access method using this control block is VSAM. 

BSTRNO- number 

specifies the number of strings initially allocated for access to the base 
cluster of a path. The default is STRNO. BSTRNO is ignored if the 
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ACB 



object being opened is not a path. If the number specified for BSTRNO is 
insufficient, VSAM will dynamically extend the number of strings as needed 
for the access to the base cluster. BSTRNO can influence performance. 
The VSAM control blocks for the set of strings specified by BSTRNO are 
allocated on contiguous virtual storage, whereas this is hot guaranteed for 
the strings allocated by dynamic extension. 

BUFND- number 

specifics the number of I/O buffers VSAM is to use for transmitting data 
between virtual and auxiliary storage. A buffer is the size of a control 
interval in the data component. The minimum number you may specify is 
1 plus the number specified for STRNO (if you omit STRNO, BUFND 
must be at least 2, because the default for STRNO is 1). The number can 
be supplied by way of the JCL DD AMP parameter as well as by way of 
the macro. The default is the minimum number required. Note, however, 
that minimum buffer specification does not provide optimum sequential 
processing performance. Generally, the more data buffers specified, the 
better the performance. Note also that additional data buffers will benefit 
direct inserts or updates during control area splits and will benefit spanned 
record accessing. For more information, see "Optimizing Performance" in 
VSAM Administration Guide. 

BUFNI = number 

specifies the number of I/O buffers VSAM is to use for transmitting the 
contents of index entries between virtual and auxiliary storage for keyed 
access. A buffer is the size of a control interval in the index. The 
minimum number is the number specified for STRNO (if you omit 
STRNO, BUFNI must be at least 1, because the default for STRNO is 1). 
You can supply the number by way of the JCL DD AMP parameter as 
well as by way of the macro. The default is the minimum number 
required. 

Additional index buffers will improve performance by providing for the 
residency of some or all of the high-level index, thereby minimizing the 
number of high-level index records to be retrieved from DASD for 
key-direct processing. For more information, see "Optimizing 
Performance" in VSAM Administration Guide. 

BUFSP - number 

specifics the maximum number of bytes of virtual storage to be used for the 
data and index I/O buffers. VSAM gets the storage in your program's 
address space. If you specify less than the amount of space that was 
specified in the BUFFERSPACE parameter of the DEFINE command 
when the data set was defined, VSAM overrides your BUFSP specification 
upward to the value specified in BUFFERSPACE. (BUFFERSPACE, by 
definition, is the least amount of virtual storage that will ever be provided 
for I/O buffers.) You can supply BUFSP by way of the JCL DD AMP 
parameter as well as by way of the macro. If you don't specify BUFSP in 
either place, the amount of storage used for buffer allocation is the largest 
of: 

• The amount specified in the catalog (BUFFERSPACE), 

• The amount determined from BUFND and BUFNI, or 
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• The minimum storage required to process the data set with its specified 
processing options 

If BUFSP is specified and the amount is smaller than the minimum 
amount of storage required to process the data set, VSAM cannot open the 
data set. 

A valid BUFSP amount takes precedence over the amount called for by 
BUFND and BUFNI. If the BUFSP amount is greater than the amount 
called for by BUFND and BUFNI, the extra space is allocated as follows: 

• When MACRF indicates direct access only, additional index buffers are 
allocated. 

• When MACRF indicates sequential access, one additional index buffer 
and as many data buffers as possible are allocated. 

If the BUFSP amount is less than the amount called for by BUFND and 
BUFNI, the number of data and index buffers is decreased as follows: 



• 



When MACRF indicates direct access only, the number of data buffers 
is decreased to not fewer than the mmimum number. Then, if required, 
the number of index buffers is decreased until the amount called for by 
BUFND and BUFNI complies with the BUFSP amount. 

• When MACRF indicates sequential access, the number of index buffers 
is decreased to not fewer than 1 more than the minimum number. 
Then, if required, the number of data buffers is decreased to not fewer 
than the minimum number. If still required, I more is subtracted from 
the number of index buffers. 

• Neither the number of data buffers nor the number of index buffers is 
decreased to fewer than the minimum number. 

If the index doesn't exist or isn't being opened, only BUFND, and not 
BUFNI, enters into these calculations. The bufferspace must not exceed 
16776704. 

CATALOG -YESINO 

specifies whether a catalog is being opened as a catalog (YES) or as a data 
set (NO). When NO is coded (or taken as the default), you can process the 
catalog with request macros (GET, PUT, etc). Your program must be 
APF-authorizcd to process a catalog as a data set. To open a password 
protected catalog for processing with VSAM macros, you must supply its 
master password. When CATALOG =* YES is coded, the catalog must be 
processed with an SVC designed for that purpose. (Access method services, 
for example, processes catalogs with SVC 26.) The request macros are 
invalid for processing a catalog "as a catalog." VSAM users should alter the 
contents of a catalog only by access method services commands. 

CRA-SCRA|UCRA 

specifies that a catalog recovery area is to be opened and that the control 
blocks are to be built in either system storage (SCRA) or user storage 
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(UCRA). If you specify SCRA and issue record management requests, you 
must operate in key 0. If you specify UCRA, you must be authorized by 
the system and you must supply the master password of the master catalog. 

DDNAME = ddname 

is 1 to 8 characters that identify the data set that you want to process by 
specifying the JCL DD statement for the data set. You may omit 
DDNAME and provide it by way of the label or by way of the MODCB 
macro before opening the data set. MODCB is described later in this 
chapter. 

EXIST = address 

specifies the address of a list of addresses of exit routines that you are 
providing. The list is established by the EXLST or GENCB macro. If you 
use the EXLST macro, you can specify its label here as the address of the 
exit list. If you use GENCB, you can specify the address returned by 
GENCB in register 1 or the label of an area you supplied to GENCB for 
the exit list. Omitting this parameter indicates that you have no exit 
routines. Exit routines are described in "User- Written Exit Routines" in 
Data Facility Product: Customization. 

MACRF - (IADR||,CNV||,KEY| 
|,CFX|NFXJ 
I. PPN IDSNI 
|,PFR|NPF| 
I,P1R||,SKQ1I,SKP1 
MCI1NC11 
l,INII,OUT| 
|,NIS|SIS| 
|,NRM|AIX| 
1.NRSIRST1 
|,NSR|LSR|GSR| 
I.NUBJUBF1) 

specifies the kind(s) of processing you will do with the data set. The 
subparameters must be meaningful for the data set. For example, if you 
specify keyed access for an entry-sequenced data set, you cannot open the 
data set. You must specify all the types of access you're going to use, 
whether you use them concurrently or by switching from one to the other. 
Figure 12 on page 38 gives the subparameters; each group of 
subparameters has a default value (indicated by underlining). You may 
specify subparameters in any order. You may specify both ADR and KEY 
to process a key-sequenced data set. You may specify both DIR and SEQ; 
with keyed access, you may specify SKP as well. If you specify OUT and 
want merely to retrieve some records as well as update, delete, or insert 
others, you need not also specify IN. 

Note: The RMODE31 parameter replaces the AMODE31 subparameter 
shown in previous releases. 
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Option Meaning 

ADR Addressed access to a key-scquenced or an entry-sequenced data 

set; RBAs are used as search arguments and sequential access is by 
entry sequence. 

CNV Access is to the entire contents of a control interval rather than to 

an individual data record. If the data set is password protected, 
you must supply the address of the control or higher-level 
password in the ACB PASS WD parameter. 

KEY Keyed access to a key-sequenced or relative record data set; keys 

or relative record numbers are used as search arguments and 
sequential access is by key or relative record number. 

CFX Control blocks and I/O buffers are to be fixed in real storage; 

MACRF = ICI must also be specified. 

NFX Control blocks and I/O buffers are fixed in real storage only 

during I/O operations. 

DDN Subtask sharea* control block connection is based on common 

ddnames. 

DSN Subtask shared control block connection is based on common 

dafar set frames. 

DFR With shared resources, writes for direct PUT requests are deferred 

until the WRTBFR macro is issued or until VSAM needs a buffer 
to satisfy a GET request; deferring writes saves I/O requests in 
cases where subsequent requests can be satisfied by the data 
already in the buffer pool. 

NDF Writes are not to be deferred for direct PUTs. 

DIR Direct access to a key-sequenced, entry-sequenced, or a relative 

record data set. 

SEP Sequential access to a key-sequenced, entry-sequenced, or a 

relative record data set. 

SKP Skip-sequential access to a key-sequenced or a relative record data 

set; used only with keyed access in a forward direction. 

ICI Processing is limited to improved control interval processing; 

access is faster because fewer processor instructions are executed. 

NCI Processing other than improved control interval processing. 

IN Retrieval of records of a key-sequenced, entry-sequenced, or a 

relative record data set; (not allowed for an empty data set). If the 
data set is password protected, you must supply the address of the 
read or higher-level password in the ACB PASSWD parameter. 

Figure 12 (Part 1 of 2). MACRF Options 
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Option Meaning 

OUT Storage of new records in a key-sequenced, entry-sequenced, or 

relative record data set (not allowed with addressed access to a 
key-scquenced data set); update of records in a kcy-scquenced, 
entry-sequenced, or relative record data set; deletion of records from a 
key-sequenced data set or relative record data set. 

If the data set is password protected, you must supply the address of 
the update or higher-level password in the ACB PASSWD parameter. 

N1S Normal insert strategy. 

SIS Sequential insert strategy (split control intervals and control areas at 

the insert point rather than at the midpoint when doing direct PUTs); 
although positioning is lost and writes arc done after each direct PUT 
request, SIS allows more efficient space usage when direct inserts are 
clustered around certain keys. 

NRM The object to be processed is the one named in the specified ddname. 

AIX The object to be processed is the alternate index of the path specified 

by ddname, rather than the base cluster via the alternate index. 

NRS Data set is not reusable. 

RST Data set is reusable (high-used RBA is reset to during OPEN). If 

the data set is password protected, you must supply the address of the 
update or higher-level password in the ACB PASSWORD parameter. 

NSR Nonshared resources. 

LSR Local shared resources. Each address space may have up to 16 index 

resource pools and 16 data resource pools independent of other 
address spaces. Unless you arc using the default, SIIRPOOL = 0, you 
must specify the "S1IRPOOL parameter to indicate which resource 
pool you are using. Specifying LSR will cause a data set to use the 
local resource pool built by the BLDVRP macro. If an index 
resource pool exists at the time an OPEN macro is issued, the index 
for a key-scquenced data set will be connected to the index resource 
pool. 

GSR Global shared resources; all address spaces may have local and global 

resources pools, where tasks in an address space with a local resource 
pool may use either the local resource pool or the global resource 
pool. 

NUB Management of I/O buffers is left up to-VSAM. 

UBF Management of I/O buffers is left up to the user; the work area 

specified by the RPL (or GENCB) AREA parameter is, in effect, the 
I/O buffer— VSAM transmits the contents of a control interval directly 
between the work area and direct access storage; valid when 
OPTCD = MVE and MACRF= CNV are specified; when ICI is 
specified, UBF is assumed. 

Figure 12 (Part 2 of 2). MACRF Options 
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iMAREA- address 

specifies the address of an optional OPEN/CLOSE or TYPE = T option 
(CLOSE macro) message area. See "OPEN/CLOSE Message Area for 
Multiple Reason or Warning Messages" on page 7 for more information. 

MLEN = number 

specifies the length of an optional OPEN/CLOSE or TYPE = T option 
(CLOSE macro) message area. Default = 0; maximum == 32K. See 
"OPEN/CLOSE Message Area for Multiple Reason or Warning Messages" 
on page 7 for more information. 

PASS\VD = address 

specifies the address of a field that contains the highest-level password 
required for the type(s) of access indicated by the MACRF parameter. The 
first byte of the field pointed to contains the length (in binary) of the 
password (maximum of 8 bytes). Zero indicates that no password is 
supplied. If the data set is password protected and you don't supply a 
required password in the access method control block, VSAM will give the 
console operator the opportunity to supply it when you open the data set. 

RMODE3I - |ALL|BUFF|CB|NONEJ 

specifics where VSAM OPEN is to obtain virtual storage (above or below 
16 megabytes) for control blocks and I/O buffers. 

The values specified by the RMODE31 parameter only have an effect on 
VSAM at the setting just before an OPEN is issued. At all other times, 
changing these values has no effect on the residency of the control blocks / 

and I/O buffers. 

ALL 

both VSAM control blocks and I/O buffers are to be obtained above 
16 megabytes. 

BUFF 

only VSAM I/O buffers are to be obtained above 16 megabytes. 

CB 

only VSAM control blocks are to be obtained above 16 megabytes. 

NONE 

both I/O buffers and VSAM control blocks arc to be built below 16 
megabytes. This is the default. 

Note: In previous releases, the MACRF subparameter AMODE31 
specified that I/O buffers were to be obtained above 16 megabytes and that 
the caller was running in 3 1 -bit addressing mode. The RMODE31 
parameter replaces the AMODE31 subparameter and the two are mutually 
exclusive. If both the AMODE31 subparameter and the RMODE31 
parameter are specified within the same program, AMODE31 is ignored. 

SHRPOOL - {number\ty 

identifies which LSR pool is to be connected to the ACB. This parameter 
is valid only when MACRF = LSR is also specified. The identification 
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number of the shared pool must be a number from to 15. The default is 
0. 

STRNO = number 

specifies the number of requests requiring concurrent data set positioning 
VSAM is to be prepared to handle. The default is 1. A request is defined 
by a given request parameter list or chain of request parameter lists. See 
"RPL Macro (Generate a Request Parameter List at Assembly Time)" on 
page 126 and "GENCB Macro (Generate a Request Parameter List at 
Execution Time)" on page 80 for information on request parameter lists. 
When records are loaded into an empty data set, the STRNO value in the 
access method control block must be 1. 

VSAM dynamically extends the number of strings as they are needed by 
concurrent requests for this ACB. This automatic extension can influence 
performance. The VSAM control blocks for the set of strings specified by 
STRNO are allocated on contiguous virtual storage, but this is not 
guaranteed for the strings allocated by dynamic extension. Dynamic string 
addition cannot be done when using the following options: 

• Load mode 

• ICI 

• LSR or GSR 

For STRNO, you should specify the total number of request parameter 
lists or chains of request parameter lists that you are using to define 
requests. (VSAM needs to remember only one position for a chain of 
request parameter lists.) However, each position beyond the minimum 
number that VSAM needs to be able to remember requires additional 
virtual storage space for: 

• A minimum of one data I/O buffer and, for keyed access, one index 
I/O buffer (the jize of ani/O buffer is the control interval size of a data 
set) 

• Internal control blocks and other areas 
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Example 1: ACB Macro 



In this example, the ACB macro is used to identify a data set to be opened and 
to specify the types of processing to be performed. The access method control 
block generated by this example is built when the program is assembled. 

BLOCK ACB AM=VSAM,BUFND=4, BLOCK gives symbolic 
BUFNI-3, address of the access 
BUFSP=19456, method control block. 
DDNAME=DATASETS, 
EXLST=EXITS, 

MACRF=(KEY, DIR, SEQ, OUT) , 
PASSWD=FIELD, 
STRN0=2 

FIELD DC FLlV.C'CHANGE 1 The update password: 

CHANGE has 6 characters. 

The ACB macro's parameters arc: 

• BUFND specifies four I/O buffers for data; BUFNI specifies three I/O 
buffers for index entries; .and BUFSP specifies 19456 bytes of buffer space, 
enough space to accommodate control intervals of data that arc 4096 bytes 
and control intervals of index entries that arc 1024 bytes. 

• DDNAME specifies that this access method control block is associated with 
a DD statement named DATASETS. 

• EXLST specifies that the exit list associated with this access method control 
block is named EXITS. 

• MACRF specifics keyed-direct and keyed-sequential processing for both 
insertion and update. 

• PASSWD specifies the location, FIELD, of the password provided. FIELD 
contains the length of the password as well as the password itself. 

• STRNO specifies that two requests will require concurrent positioning. 
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ACB 



In this example, the ACB macro is used to identify a data set to be opened and 
to specify the types of processing to be performed. An LSR pool is connected to 
the data set. The access method control block generated by this example is built 
when the program is assembled. The caller requests that the VSAM control 
blocks and I/O buffers be obtained above 16 megabytes if possible. 



BL0CK2 ACB AM=VSAM, 

DDNAME=DATASETS, 

EXLST=EXITS, 

MACRF=(KEY,DIR, 

LSR,SEQ,OUT), 

PASSWD=FIELD, 

RM0DE31=ALL, 

SHRP00L=1 

FIELD DC FLl' 6*, C' CHANGE* 



BL0CK2 gives symbolic 
address of the access 
method control block. 



The update password: 
CHANGE has 6 characters 



The ACB macro's parameters are: 

• DDNAME specifics that this access method control block is associated with 
a DD statement named DATASETS. 

• EXLST specifics that the exit list associated with this access method control 
block is named EXITS. 

• MACRF specifies keyed-direct and keyed-sequential processing for both 
insertion and update. LSR indicates that the Ii»R pool created by BLDVRP 
is to be connected to the data set. 

• PASSWD specifies the location, FIELD, of the password provided. FIELD 
contains the length of the password as well as the password itself. 

• RMODE31 = ALL specifies that you want both VSAM control blocks and 
I/O buffers to reside above 16 megabytes. 

• SHRPOOL specifies that the LSR pool with the identification number of 1 is 
to be used. However, if an index resource pool exists at the time the OPEN 
macro is issued, the index for the key-sequenced data set will be connected to 
the index resource pool. 
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ACQRANGE Macro (Stage Data) 

The format of the ACQRANGE macro is: 



\label\ ACQRANGE RPL - address 



RPL = address 

specifies the address of the RPL that identifies your open data set and your 
argument range. RPL parameters that have meaning for ACQRANGE are 
as follows: 

ACB = address 

identifies your VSAM data set. 

ARG «■ address 

identifies your starting and ending arguments. Address points to a 
parameter list, aligned on a fullword boundary as follows: 

KEY-SEQUENCED DATA SET 

Onset Length Contents 

4 Feedback area: Address 

ofanECB WAIT list 

4 K Starting full argument 

(K = key length) 

4+K K (K = key length) 

ENTRY-SEQUENCED DATA SET OR RELATIVE RECORD 
DATA SET 

Offset Length Contents 

4 Feedback area: Address 

ofanECB WAIT list 

4 4 Starting RBA/RRN 

8 4 Ending RBA/RRN 

The maximum number of argument pairs you may specify is one. 

OPTCD = ({ADR|KEY} 

,{ASY|SYN} 
,{KEQ|KGE} 
,FKS) 

ADR is valid for an entry-sequenced data set, error for key-sequenced 
data set or relative record data set. 
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KEY is valid for key-sequenced data set and relative record data set, 
error for entry-sequenced data set. 

If ASY is specified, you cannot WAIT on the RPLECB field for 
MNTACQ or ACQRANGE. You use the address placed in the 
parameter list feedback area. This address points to a list of event 
control blocks (ECB) (in standard WAIT list format) which you may 
use in place of the RPLECB field. 

GEN is not supported; if specified, it will give an error indication. 

All other OPTCD subparameters are not applicable, and, if specified, 
are ignored with no error indication. 

Because your request may result in the staging of numerous cylinders, a single 
ECB is not sufficient for an asynchronous ACQRANGE request. The RPLECB 
field is inoperative for the ACQRANGE interface. Upon return from an 
asynchronous ACQRANGE, the feedback area of the ACQRANGE parameter 
contains the address of a standard ECB WAIT list. You must then use this list 
in conjunction with either the WAIT macro or the EVENTS macro of MVS. 
An asynchronous request must conclude with cither CHECK, ENDREQ, or 
CLOSE. The parameter list cannot be reused until the CHECK, ENDREQ, or 
CLOSE is completed. 

At the conclusion of this macro, the RPL is disconnected. Any positioning in 
effect prior to execution of ACQRANGE will be lost. You may have to 
reposition. Chained RPLs are not supported by this macro. 
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BLDVRP Macro (Build VSAM Resource Pool) 



The format of the BLDVRP macro is: 



BLDVRP 



BUFFERS ■» (sizeinumber^izeinumber)^..) 
|,FIX = {BFR|IOB|(BFR,IOB)}| 
IKEYLEN- length] 

|,RMODE3l = {ALL|BUFF|CB|NONE}| 
I,SHRPOOL= [0\number}\ 
|,MODE={24|3T}| 
,STRNO = number 
|,TYPE={LSR(,DATA|INDEXJ | GSR}| 



Note: The RMODE31 parameter replaces the LOC= BELOW|ANY parameter 
shown in previous releases. 

The BLDVRP macro has a standard form and list and execute forms. The 
standard form builds a parameter list and passes control to VSAM to build the 
resource pool. The list and execute forms are described in Appendix B, "List, 
Execute, and Generate Forms of Macros" on page 171. 

BUFFERS = (size{number)ySize{number)y...) 

specifics the size and number of buffers in each buffer pool in the resource 
pool. The number of buffer pools in the resource pool is implied by the 
number of size(numbcr) pairs you specify. 

When you process a kcy-scqucnced data set, the index component, as well 
as the data component, shares the buffers of a buffer pool. When you use 
an alternate index to process a base cluster, the components of the alternate 
index and the base cluster share buffers. The components of alternate 
indexes in an upgrade set share buffers. Buffers of the appropriate size and 
number must be provided for all these components. Each component uses 
the buffer pool with buffers either the required size or larger. 

size 

is 512, 1024, 2048, 4096, and then in increments of 4096 to a 
maximum of 32K bytes. 

number 

is at least 3. 

Size times number must be less than 16 megabytes. 

FIX= {BFR|IOB|(BFR,IOB>} 

specifies that I/O buffers (BFR), or I/O-rclatcd control blocks (IOB), or 
both, are to be fixed in real storage. With GSR, IOB includes channel 
programs. If the program that issues BLDVRP with FIX specified is not 
authorized to fix areas in real storage, FIX is ignored. A program is 
authorized if it is in supervisor state with protection key to 7, or has been 
link-edited with authorization (the authorized program facility is described 
in Supervisor Services and Macro Instructions). 



46 MVS/XA VSAM Administration: Macro Instruction Reference 



BLDVRP 

Note: If FIX is specified, DLVRP must be issued by the same task that 
issues BLDVRP. 

KEYLEN = /*/#/* 

specifies the maximum key length of the data sets that are to share the 
resource pool. The default is 255. The keys whose lengths must be 
provided for are the prime key of each key-sequenced data set and the 
alternate key of each alternate index that is used for processing or is being 
upgraded. If none of the data sets is keyed, specify 0. 

RMODE31 - fALLIBLFFICBI NONE) 

specifies the storage residence location of the buffers and I/O related control 
blocks of the LSR pool identified with the SIIRPOOL keyword. 

The RMODE31 parameter tells the VSAM OPEN routines where to 
obtain storage for the I/O related control blocks and I/O buffers. 
Therefore, the only time the values specified by the RMODE31 parameter 
have any effect on VSAM is on the setting just before an OPEN is issued. 
At other times, changing these values has no effect on the residency of the 
I/O related control blocks and I/O buffers. 

Note: The RMODE31 parameter is valid only when TYPE = LSR is 
specified. 

ALL 

both I/O buffers and the VSAM I/O related control blocks associated 
with the pool are to reside above 16 megabytes. 

BUFF 

specifics that only I/O buffers arc to reside above 16 megabytes. 

CB 

only the VSAM I/O related control blocks associated ^whh the pool 
, t arc to reside above 16 megabytes. 

NONE 

both I/O buffers and the VSAM I/O related control blocks associated 
with the pool are to reside below 16 megabytes. This is the default. 

Note: In previous releases, the LOC = (BELOW|ANY) parameter was 
used to specify that buffers in the pool be created above 16 megabytes. The 
RMODE31 parameter replaces the LOC parameter and the two parameters 
are mutually exclusive. If both are specified on the BLDVRP macro, the 
LOC parameter is ignored. 

SHRPOOL={0|ra/m£er} 

specifics the identification number of a shared resource pool. Valid only 
when TYPE = LSR is also specified or defaulted. This parameter also 
requires that the RMODE31 parameter be specified. 



specifies the shared pool with the ID of 0. It is the default LSR pool. 
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number 

specifies the shared pool with the ID of number where number can be 
to 15. The LSR control block and buffer pool residence is 
determined by the RMODE31 = keyword. 

MODE- {24|31} 

specifies the format of the BLDVRP parameter list that is to be generated. 



24 



31 



specifies that a standard form (24-bit) parameter list address be 
generated. This is the default. 



specifies that a long form (31 -bit) parameter list address be generated. 
This value must be coded if the parameter list resides above 16 
megabytes. 

STRNO = number 

specifies the total number of placeholders required for all the data sets that 
are to share the resource pool. 1 is minimum; 255 is maximum. 

The number should equal the potential number of requests that may be 
issued, concurrently for all the data sets that wilt share the resource pooL If a 
request fails because the number of placeholders is insufficient (you receive a 
reason code of 64 (X'40') in the RPL feedback area), you may retry the 
request; it will be assigned a placeholder if one has been released. See 
Figure 8 on page 17 for a complete description of reason code 64 (X'40"). 

TYPE= {LSRI,DATA|INDEX| | GSR) 

specifies whether a local (LSR) or a global (GSR) resource pool is to be 
built. 

LSR 

specifies that the caller requests a local shared resource pool. A 
maximum of 16 data and 16 index resource pools can be built in one 
address space. Each resource pool must be built individually. 

DATA 

specifics that the caller wants to build a data resource pool. This 
option requires that LSR be specified. This resource pool must exist 
before an index pool with the same shared pool ID can be built. 

INDEX 

specifies that the caller wants to build an index resource pool. This 
option requires that LSR be specified or defaulted. INDEX must be 
specified in order to create a separate index resource pool. If it is not 
specified, both data and index components will use the data pools. A 
data pool must already exist before an index pool with the same 
shared pool ID can be built. 

GSR 

specifies that the caller requests a global shared resource pool. 
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Only one BLDVRP TYPE = GSR may be issued for the system for each of 
the protection keys through 7. The program that issues BLDVRP 
TYPE = GSR must be in supervisor state with protection key to 7. 



Example 1. Obtaining an LSR Pool above 16 Megabytes 



This example shows how both a local shared resource pool and a BLDVRP 
parameter list residing above 16 megabytes are obtained. 

P00L1 BLDVRP BUFFERS=(1024(5)), 
STRN0=4, 
TYPE=LSR, 
M0DE=31, 
RM0DE31=ALL 

The BLDVRP parameters are: 

• BUFFERS specifies that there is one buffer pool in the resource pool. This 
buffer pool contains 5 buffers, and each of these buffers is 1024 bytes. 

• STRNO specifies that 4 placeholders arc required for the data sets to share 
the resource pool. 

• TYPE specifics that a local resource pool is to be built. 

• MODE specifies that a parameter list is to be generated that may reside 
above or below 16 megabytes. The value of 31 must be coded if the 
parameter list resides above 16 megabytes. 

• RMODE31 specifies the location in storage for the I/O buffers and I/O 
related control blocks of the LSR pool. 

To connect the LSR pool to the data set, you must code the LSR and 
S11RPOOL parameters on the ACB. See "ACB Macro (Generate an Access 
Method Control Bloc!: at Assembly Time)" on page 34. 
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| Example 2. Request for Separate Data and Index Resource Pools 



This example shows how the two separate data and index resource pools with an 
identification equal to 3 are created. 



P00L1 


BLDVRP 


BUFFERS=( 2048(4)), 

TYPE=(LSR,DATA), 

SHRP00L=3, 

STRN0=2, 

RM0DE31=ALL 






LTR 
BNZ 


R15,R15 
ERROR 


Check return code. 
Do not build index if 


* 






error. 


P00L2 


BLDVRP 


BUFFERS=( 1024(5)), 
TYPE=(LSR, INDEX), 
SHRP00L=3, 
STRN0=2, 
RM0DE31=ALL 





Note: POO LI must be created first because the data pool must exist before the 
index pool with the same shared pool ID can be built. Also, only one data and 
one index pool can be built for a shared pool ID. 
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CHECK Macro (Wait for Completion of Request) 



The format of the CHECK macro is: 



llabell CHECK RPL - address 



where: 



label 



is 1 to 8 characters that provide a symbolic address for the CHECK macro. 

RPL » address 

specifics the address of the request parameter list that defines the request. 
You may specify the address in register notation (using a register from 1 
through 12, enclosed in parentheses) or specify it with an expression that 
generates a valid relocatable A-type address constant. 



Example 1: Check Return Codes after an Asynchronous Request 



In this example, return codes arc checked after an asynchronous request. The 
CHECK macro is used to cause an exit to be taken if there is a logical or 
physical error or if the end of the data set is reached. 

REQPARMS RPL OPTCD=ASY 



GET RPIr=REQPARMS 



LTR 



BNZ 



15,15 



REJECTED 



CHECK RPL=REQPARMS 



LTR 15,15 
BNZ FAILURE 



Was the request completed 
successfully? 

Zero indicates the request was 
accepted. If it was not 
accepted, register 15 contains 
4i REQPARflS is active for 
another request. Continue to 
work on something that is not 
dependent on the request. 

CHECK would cause one of the 
three exits to be taken if 
there was a logical or physical 
error or if the end of the 
data set was reached and an 
active exit list exists. 

Test return indication is 
register 15. 

Zero indicates the request 
completed successfully. If 
it failed, register 15 
contains 8 or 12: there was 
a logical or a physical 
error. 



REJECTED . . . 
FAILURE . . . 
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Unless you provide exit routines that terminate processing, always test register 15 
after the CHECK. If a routine returns to VSAM, register 15 is reset and control 
is passed back to your program immediately after the CHECK. An error analysis 
routine normally issues SHOWCB or TESTCB to examine the feedback field in 
the request parameter list, so that, when your processing program gets control 
back, it doesn't have to analyze the errors— but it may" alter its processing if there 
was an error. If you don't provide an error analysis routine, your program can 
issue SHOWCB or TESTCB to analyze an error when it gets control back 
following the CHECK. 



Example 2: Check Return Codes after a Synchronous Request 



With synchronous processing, you should test register 15 after the request 
because the request may not have been accepted (register 15 contains 4) or 
because an error might have occurred (8 or 12): 

GET RPL=REQPARMS 

LTR 15,15 Was the request completed 

successfully? 

BNZ REJFAIL If branch is not taken, was 

the request accepted and 
completed succes fully? 



REJFAIL 
Example 3: Overlap Processing 



In this example, the CHECK macro is used to wait for completion of a request 
before continuing to other processing. Access is asynchronous. 

BLOCK ACB 

LIST RPL ACB=BLOCK, Asynchronous access. 
AREA=WORK, 
AREALEN=50, 
OPTCD=ASY 



LOOP GET 


RPL=LIST 


LTR 


15,15 


BNZ 


NOTACCEP 


Do other processing. 


CHECK 


RPL=LIST 



Suspends your processing to wait 
for completion of GET if 
necessary and to cause VSAM to 
indicate return codes. 
LTR 15,15 



BNZ ERROR 
Process the record. 
B LOOP 
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NOTACCEP ... 
ERROR 



Request was not accepted. 
Request failed. 



WORK 



DS 



CL50 



Work area. 



After issuing the request, make sure that VSAM accepted it before you go on to 
other processing. When you have done as much other processing as you can, 
issue the CI IECK macro. VSAM will not give you back control until the 
request is complete. If you don't want to issue CHECK until you know the 
request is complete, use the ECB parameter of the RPL macro or the 
lO = COMPLETE parameter of the TESTCB macro. After you issue the 
CHECK, VSAM immediately returns a code and takes an exit, if necessary. See 
"RPL Macro (Generate a Request Parameter list at Assembly Time)" on 
page 126 and "GENCB Macro (Generate a Request Parameter List at Execution 
Time)" on page 80 for information on the ECB parameter. 



Example 4: Suspend a Request for Many Records 



In this example, a CHECK macro is issued for the first request parameter list in a 
chain of parameter lists. If an error occurred for one of the request parameter 
lists in the chain and you have supplied error analysis routines, VSAM takes a 
LERAD or SYNAD exit before it returns control to your program after the 
CHECK. 



FIRST 


RPL 


ACB=BL0CK, 

AREA=AREA1, 

AREALEN=50, 

NXTRPL=SECOND, 

OPTCD=ASY 


SECOND 


RPL 


ACB=BL0CK, 

AREA=AREA2, 

AREALEN=50, 

NXmPL=THIRD^ 

0PTCD=ASY 


THIRD 


RPL 


ACB=BL0CK, 
AREA=AREA3, 
AREALEN=50, 
0PTCD=ASY 


LOOP 


GET 


RPL=FIRST 




LTR 


15,15 




BNZ 


NOTACCEP 


Do other 


proces 


sing. 




CHECK 


RPL=FIRST 




LTR 


15,15 




BNZ 


ERROR 



Last list does not indicate 
a next list. 



Request gives the address of 
the first request parameter 
list. 
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Process the three records retrieved by the GET. 



B 



NOTACCEP 
ERROR 

AREA1 

AREA2 - 
AREA3 



DS 

DS 
DS 



LOOP 



CL50 

CL50 
CL50 



Request wasn't accepted. 

Display the feedback field 
(FIELDS=FDBK) of each request 
parameter list to find 
out which one had an error. 

A single GET request causes VSAM 
to put a record in each of AREA1, 
AREA1, and AREA3. 



After the CHECK, register 15 is set to indicate the status of the request. A code 
of indicates that no error was associated with any of the request parameter lists. 
Any other code indicates that an error occurred for one of the request parameter 
lists. You should issue a SIIOWCB macro for each request parameter list in the 
chain to find out which one had an error. VSAM doesn't process any of the 
request parameter lists beyond the one with an error. 
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CLOSE Macro (Disconnect Program and Data) 

The format of the CLOSE macro is: 



\Iabel\ 



CLOSE 



(address\,(options)\ t ...) 

|,MODE={24|31}| 

|,TYPE«T| 



where: 

label 

is 1 to 8 characters that provide a symbolic address for the CLOSE macro. 

address 

specifies the address of the access method control block or DCB for each 
data set to be closed. You may specify the address in register notation 
(using a register from 2 through 12— in parentheses) or specify it with an 
expression that generates a valid relocatable A-type address constant. If 
you specify only one address with a register, you must enclose the 
expression identifying the register in two sets of parentheses: for example, 
CLOSE ((2)). 

options 

are options parameters for use only in closing non-VSAM data sets. If any 
options arc specified with the address of an access method control block, 
VSAM ignores them. 

Note: Because the CLOSE parameters arc positional, include a comma for 
options (even if you don't specify options) before a subsequent parameter. 

MODE={24|31) 

specifics the format of the CLOSE parameter list that is to be built. 



24 



specifies that a standard form (24-bit) parameter list address be built. 
This parameter list must reside below 16 megabytes and contain the 
address of ACBs residing below 16 megabytes. The caller, however, 
may be above 16 megabytes. This is the default parameter list 
format. 



31 



specifies that a long form (31 -bit) parameter list address be built. 
This list can reside above or below 16 megabytes. This value must be 
coded if the parameter list resides above 16 megabytes or contains the 
address of an VSAM/VTAM ACB residing above 16 megabytes. 

TYPE = T 

specifics that VSAM is to complete outstanding I/O operations and update 
the catalog, but not disconnect the program from the data. 

You can issue a temporary CLOSE macro to cause VSAM to complete 
outstanding I/O operations, put back into the catalog the updated 
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information that was brought into virtual storage when the data set was 
opened, and write records in the SMF data set if you are using SMF. A 
temporary CLOSE doesn't disconnect the program from the data set, so 
your program can continue to process the data set without issuing an 
OPEN macro again. 

You must close and reopen a newly created VSAM data set before you can 
issue noncreate requests. A temporary close is not adequate for this 
purpose. 

Note: If you are sharing subtasks or if you have issued an asynchronous request 
for access to a data set, you must issue a CHECK or an ENDREQ on all RPLs 
before you issue a CLOSE or CLOSE TYPE-T; otherwise, concurrent data set 
I/O activity will cause unpredictable results during a close. 



Example: CLOSE Macro 



This example shows how to close an ACB with a parameter list that may reside 
above 16 megabytes. 



BL0CK1 



ACB 



,RM0DE31=ALL 



VSAM control blocks 
and I/O- buffers may 
be above 16 megabytes 



OPEN 



CLOSE 



BL0CK1, 
M0DE=31 



BL0CK1, 

M0DE=31, 

TYPE=T 



OPEN/CLOSE parameter 
list may reside above 
16 megabytes 



The CLOSE parameters are: 

• MODE = 31 is required if the OPEN/CLOSE parameter list resides above 16 
megabytes or if the ACB resides above 16 megabytes. 

• TYPE indicates a temporary CLOSE. This causes VSAM to complete 
outstanding I/O operations, put back into the catalog the updated 
information that was brought into virtual storage when the data set was 
opened, and write records in the SMF data set if you are using SMF. 
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CNVTAD 
CNVTAD Macro (Convert Address) 

The format of the CNVTAD macro is: 



\label\ CNVTAD RPL - address 



RPL = address 

specifics the address of the request parameter list (RPL). The RPL 
identifies your opened VSAM data set and your arguments. The following 
RPL parameters and subparameters have meaning for the CNVTAD 
macro: 

ACB = address 

identifies your VSAM data set. 

ARG «= address 

identifies your arguments. The address points to a parameter list, 
aligned on a fullword boundary as follows: 

Kcy-scquenccd data set 



OfTsct 


Length 


Contents 





3 


Reserved; unused 


3 


1 


Number of arguments (N) 
(N = 1 to 255) 


4 + (N-l)(10+K) 


4 


Feedback RBA 
(K - key length) 


8 + (N-l)(10+K) 


4 


Feedback volume serial number 
(K = key length) 


14+(N-1)(10+K) 


K 


Full key argument 
(K = key length) 


Entry-sequenccd data set or relative record data set 


OfTsct 


Length 


Contents 




3 

4 + (N-l)(4) 

8 + (N-l)(14) 

18 + (N-1)(14) 


3 
1 
4 
6 
6 


Reserved; unused 

Number of arguments (N) 

Feedback RBA 

Feedback volume serial number 

RBA/RRN argument 



The value for K is always 4 in an entry-sequenccd or relative record 
data set. Therefore, 10 + K is always 14 for these two types of data 
sets. The maximum number of arguments allowed is 255. 
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ECB - address 

specifies the address of an event control block (ECB) which you may 
specify. VSAM indicates in the ECB whether or not a request is 
complete. This parameter is optional. 

OPTCD«({ADR|KEY} 

,{ASY|SYN} 
,{KEQ|KGE} 
,FKS) 

ADR is only valid for entry-sequenced data sets. 

KEY is only valid for key-sequenced data sets and relative record dat 
a sets. 

If ASY is specified, you cannot WAIT on the RPLECB field for 
MNTACQ or ACQRANGE. You use the address placed in the 
parameter list feedback area. This address points to a list of ECBs (in 
standard WAIT list format) which you may use in place of the 
RPLECB field. 

GEN is not supported; if specified, it will give an error indication. 

All other OPTCD subparameter& ate not applicable, and, if specified, 
arc ignored with no error indications. 

For a given list of discrete arguments, CNVTAD returns the volume serial 
number (volser) and the RBA corresponding to each argument in the parameter 
list feedback area. The data portion of your VSAM data set is not referenced and 
need not be mounted even if the sequence set is embedded. 

For an entry-sequenced data set, the volser is returned, and the same RBA 
specified in the argument field is also returned. 

Note: The RBA returned by CNVTAD in the case of a key-sequenced data set 
is not the exact RBA of the record. It is, in fact, an approximate value. (For 
data sets with the IMBED option, it is the RBA of the beginning of the sequence 
set for the record's control area; for data sets with NOIMBED, it is the RBA of 
the record's control interval.) When passed to MNTACQ, these RBA values 
cause MNTACQ to stage the appropriate cylinders corresponding to the 
requested arguments originally passed to CNVTAD. You should therefore use 
caution if you arc planning to use the RBAs obtained from CNVTAD for any 
purpose other than as input to MNTACQ. 

At the conclusion of this macro, the RPL is disconnected. Any positioning in 
effect prior to execution of this macro will be lost. You may have to reposition. 
Chained RPLs are not supported by CNVTAD. 
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DLVRP Macro (Delete VSAM Resource Pool) 

The DLVRP macro has a standard form and an execute form. The standard 
form builds a parameter list and passes control to VSAM to delete the resource 
pool. The execute form is described in Appendix B, "List, Execute, and 
Generate Forms of Macros" on page 171. 

The format of the DLVRP macro is: 



DLVRP 



TYPE = {LSR |GSR} 
|,MODE-{24|3l)| 
|,SHRPOOL = {0\number}\ 



TYPE = {LSR |GSR} 

specifies the type of resource pool to be deleted: local (I.SR) or global 

(GSR). When deleting an LSR pool, the number specified on the 

SI IR POOL parameter indicates which LSR pool is to be deleted. If both a 

data resource pool and an index resource pool have the same SIIRPOOL 

number, both will be deleted. The program that issues DLVRP 

TYPE = GSR must be in supervisor state with protection key to 7. 

MODE ={24|31} 

specifies the format of the DLVRP parameter list that is to be generated. 



24 



specifics that a standard form (24-bit) parameter list address be built. 
This parameter list must reside below 1 6 megabytes and contain the 
address of ACBs residing below 16 megabytes. The caller, however, 
may be above 16 megabytes. This is the default parameter list 
format. 



31 



specifics that a long form (31 -bit) parameter list address be built. 
This list can reside above or below 16 megabytes. This parameter 
value must be coded if the parameter list resides above 16 megabytes 
or contains the address of a VSAM/VTAM ACB residing above 16 
megabytes. 

SHRPOOL- {^number} 

specifies the identification number of the shared resource pool that is to be 
deleted. Valid only when TYPE - LSR is also specified. The DLVRP 
parameter list may reside above or below 16 megabytes. 



specifics the shared pool with the identification of 0. This is the 
default LSR pool identification number. 

number 

specifies the shared pool with the identification of number where 
number is a number from to 15. 
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Example: DLVRP Macro 



This example shows how an LSR pool with a parameter list that may reside 
above 16 megabytes and identification number other than is deleted. 

DELPOOL DLVRP TYPE=LSR, 
M0DE=31, 
SHRP00L=1 

The DLVRP parameters are: 

• TYPE specifies that an LSR pool is to be deleted. 

• MODE = 31 specifies the parameter list may reside above or below 16 
megabytes. 

• SHRPOOL specifies that the data resource pool and the index resource pool 
(if any) with the identication number of 1 are to be deleted. 
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ENDREQ Macro (Terminate a Request) 

The format of the ENDREQ macro is: 



\label\ 


ENDREQ 


RPL ■* address 



where: 



label 

is 1 to 8 characters that provide a symbolic address for the ENDREQ 
macro. 

RPL = address 

specifies the address of the request parameter list that defines the request. 
You may specify the address in register notation (using a register from 1 
through 12, enclosed in parentheses) or specify it with an expression that 
generates a valid relocatable A-type address constant. 

Note: The ENDREQ macro must not be issued when records are being loaded 
into a VSAM data set (load mode). ENDREQs issued while in load mode are 
ignored. 



Example: Release Positioning for Another Request 



In this example, the ENDREQ macro is used to cause VSAM to release 
exclusive control of a control interval containing a record. There are two request 
parameter lists, both of which require VSAM to have the ability to remember its 
position until VSAM is explicitly requested to forget its position. 



VSAM must remember its 
position. 

VSAM must remember its 
position and maintain 
exclusive control until 
explicitly requested to 
forget it by PUT or 
ENDREQ. 



BLOCK 


ACB 


MACRF=(SEQ, 
DIR),STRN0=2 


^EQ 


RPL 


ACB=BLOCK, 
OPTCD=SEQ 


DIRUPD 


RPL 


ACB=BLOCK, 
OPTCD=(DIR,UPD) 



LOOP 



GET 


RPL=SEQ 


LTR 


15,15 


BNZ 


ERROR 


GET 


RPL=DIRUPD 


LTR 


15,15 


BNZ 


ERROR 



VSAM now remembers its 
position for this request 
only while it is 
processing the request. 



VSAM can remember its 
position for this request. 
The control interval will 
be placed in exclusive 
control until either 
ENDREQ or PUT UPD is 
issued. 
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Decide whether to update the record. 



B 


FORGET 


PUT 


RPL=DIRUPD 


LTR 


15,15 


BNZ 


ERROR 


B 


LOOP 


ENDREQ 


RPL=DIRUPD 


LTR 


15,15 


BNZ 


ERROR 


B 


LOOP 


XXX 





No; do not update the 

record. 

Yes; update the record, 

causing VSAM to forget its 

position for DIRUP. 



FORGET ENDREQ RPL=DIRUPD Cause VSAM to forget its 

position for DIRUPD. 
Release exclusive control. 



ERROR xxx Request wasn't accepted or 

failed. 

The use of ENDREQ illustrated here causes VSAM to release exclusive control 
of the control interval for a record. When PUT is issued after a DIRUPD GET 
request, ENDREQ need not be issued, because PUT causes VSAM to release 
exclusive control (the next DIRUPD GET doesn't depend on VSAM's 
remembering its position). Another result of ENDREQ is that current buffers 
arc written if they have been modified. 

To cause VSAM to give up its position associated with a chain of request 
parameter lists, specify the first request parameter list in the chain in your 
ENDREQ macro. 

ENDREQ can also be used to cancel an asynchronous request, rather than 
suspending processing with CHECK. 

Note: If you are sharing subtasks or if you have issued an asynchronous request 
for access to a data set, you must issue a CHECK or an ENDREQ on all RPLs 
before you issue a CLOSE or CLOSE TYPE = T; otherwise, concurrent data set 
I/O activity will cause unpredictable results during a close, in is adequate. 

Because VSAM remembers its position after a direct GET with OPTCD = UPD 
or LOC, if no PUT or ENDREQ follows, you can switch to sequential access 
and use the positioning for a GET. 
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ERASE Macro (Delete a Record) 



The format of the ERASE macro is: 



[!abel\ 


ERASE 


RPL« address 



where: 



label 



is 1 to 8 characters that provide a symbolic address for the ERASE macro. 



RPL« address 

specifics the address of a request parameter list that defines the request. 
You may specify the address in register notation (using a register from 1 
through 12, enclosed in parentheses) or specify it with an expression that 
generates a valid relocatable A-typc address constant. 

With ERASE processing of key-sequenced data sets, VSAM attempts to make 
the control interval available to the control area when the last record in the 
control interval is erased. 'lTius, key-scqucnccd data set control intervals can be 
reused for new records whose keys fall anywhere within the control area's range 
of keys. You may suppress the process of reclaiming the control interval by 
setting RPLNOCIR in the RPL used for ERASE. The high key control interval 
of a control area is never reclaimed. 



Example 1: Keyed- Direct Deletion 



In this example, GET and ERASE macros are used to retrieve and delete records. 
Not every record retrieved for deletion is deleted. The search argument is a full 
key (5 bytes), compared equal. 



DELETE ACB 



LIST 



RPL 



MACRF=(KEY,DIR, 
OUT) 

ACB=DELETE, 

AREA^ORK, 

AREALEN=50, 

ARG=KEYFIELD, 

OPTCD=(KEY,DIR, 

SYN,UPD, 

MVE,FKS, 

KEQ) 



UPD indicates deletion. 



LOOP 



MVC KEYFIELD, source 



GET 



Search argument for 
retrieval, from a table 
or transaction record. 



RPL=LIST 



LTR 15,15 
BNZ ERROR 
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ERASE 



Decide whether to delete the record. 

BE LOOP 

ERASE RPL=LIST 

LTR 15,15 

BNZ ERROR 

B LOOP 
ERROR 



No; retrieve the next record. 
Yes; delete the record. 



WORK DS 
KEYFIELD DS 



CL50 
CL5 



Request was not accepted, or 
failed. 

Examine the data record here. 

Search argument. 



When you retrieve a record for deletion (OPTCD= UPD, same as retrieval for 
update), VSAM is positioned at the record retrieved, in anticipation of a 
succeeding ERASE (or PUT) request for that record. You arc not required to 
issue such a request, though. Another GET request nullifies any previous 
positioning for deletion or update. 

Keyed-sequential retrieval for deletion varies from direct in not using a search 
argument (except for possible use of the POINT macro). Skip-sequential 
retrieval for deletion (OPTCD = (SKP,UPD)) has the same effect as direct, but it 
is faster or slower depending on the number of control intervals separating the 
records being retrieved. 



Example 2: Addrcsscd-Scqucntial Deletion 



In this example, the ERASE macro is used to delete records from a 
kcy-scqucnced data set. Not every record retrieved for deletion is deleted. 
Skipping is effected by the POINT macro. 



DELETE ACB 



REQUEST RPL 



MACRF=(ADR,SEQ, 
OUT) 

ACB=DELETE, 

AREA=WORK, 

AREALEN=100, 

ARG=ADDR, 

OPTCD=(ADR,SEQ, 

ASY 

UPD^MVE) 



UPD indicates deletion. 



LOOP . . . Decide whether you need to 

skip to another position 
forward or backward) . 

B RETRIEVE No; bypass the POINT. 

MVC ADDR, source Yes; move search argument 

for POINT into 
search -argument field. 
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ERASE 



POINT RPL=REQUEST 



LTR 


15,15 


BNZ 


ERROR 


CHECK 


RPL=REQUEST 


LTR 


15,15 


BNZ 


ERROR 


RETRIEVE GET 


RPIr=REQU£ST 


LTR 


15,15 


BNZ 


ERROR 


CHECK 


RPL=REQUEST 


LTR 


15,15 


BNZ 


ERROR 


Decide whether to delete the record. 


BE 


LOOP 


ERASE 


RPL=REQUEST 


LTR 


15,15 


BNZ , 


ERROR 


CHECK 


RPL=REQUEST 


LTR 


15,15 


BNZ 


ERROR 


B 


LOOP 



Position VSAM to the 
record to be retrieved 
next . 



No; skip ERASE and CHECK. 
Yes; delete the record. 



ERROR 



Request was not accepted, 
or failed. 



ADDR 
WORK 



DS 
DS 



F 
CL100 



RBA search argument for 

POINT. 

Work area. 



Addressed deletion is allowed only for a key-sequenced data set. The records of 
an entry-sequenced data set are fixed. When records are deleted using addressed 
deletion from a kcy-scquenccd data set, the index is not updated. 
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EXLST Macro (Generate an Exit List at Assembly Time) 

The format of the EXLST macro is: 



\label\ 


EXLST 


IAM-VSAMI 

(,EODAD - (address\,A\K\[,L\)\ 
I,IOPID = (address)) 
MRNAD = (address\,A\M,U)\ 
(,LERAD - (address\,A\X\m)\ 
|,SYNAD - (a<Mrew[,A|N||,L|)| 
|,UPAD = (addres4,A\>i\m)\ 



Values for EXLST macro subparamctcrs can be specified as absolute numeric 
expressions, character strings, codes, and expressions that generate valid 
relocatable A-type address constants. 

Note: See Data Facility Product: Customization for the factors that determine 
the addressing mode and the parameter list residency mode set when the exit 
routine gets control. 



label 



is 1 to 8 characters that provide a symbolic address for the exit list that is 
established. 

AM- VSAM 

specifics that the access method using the control block is VSAM. 

EODAD = (address\,A\X\\M) 
IOPID = (address) 
JRNAD - (adtirajf ,A|N||,L|) 
LERAD - (address\,A\>i\m) 
SYN AD = (addres4,A\X]\,L\) 
UPAD - (a</ctej|,A|N|l,A|) 

specify that you are supplying a routine for the exit specified. 

For more information about user exit routines, see Data Facility Product: 
Customization. 

The exits and values that can be specified for these routines are: 

EODAD 

specifies that an exit is provided for special processing when the end 
of a data set is reached by sequential access. 

IOPID 

specifies that an I/O prevention identifier is provided to terminate I/O 
and prevent new I/O from being started for the data sets associated 
with the identifier. When the IOPID address is specified, the 
identifier is always assumed to be active. 
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JRNAD 

specifies that an exit is provided for journalizing transactions as you 
process data records. 

LERAD 

specifies that an exit is provided for analyzing logical errors. 

SYNAD 

specifics that an exit is provided for analyzing physical errors. 

UPAD 

specifies that an exit is provided for user processing during a VSAM 
request. The GENCB, MODCB, SIIOWCB, and TESTCB macros 
do not support the UPAD user exit routine. 

address 

is the address of a user-supplied exit routine or an I/O prevention 
identifier. The address must immediately follow the equal sign. 



A|N 



Example: EXLST Macro 



specifies that the exit routine is active (A) or not active (N). VSAM 
docs not enter a routine whose exit is marked not active. 



specifics that the address is that of an 8-byte field that contains the 
name of an exit routine in a partitioned data set that is identified by a 
JOBLIB or STEPLIB DD statement or in SYS1.LINKLIB. VSAM 
is to load the exit routine for exit processing. If L is omitted, the 
address gives the entry point of the exit routine in virtual storage, and 
the exit routine is entered in the addressing mode of the VSAM caller. 



In this example, an EXLST macro is used to identify exit routines that are 
provided for analyzing logical and physical errors. The label, EXITS, of the 
EXLST macro is used in an ACB or GENCB macro that generates an access 
method control block to associate the exit list with an access method control 
block. The exit list generated by this example is built when the program is 
assembled. 

EXITS EXLST EODAD=( ENDUP, N), EXITS gives symbolic 

LERAD=LOGICAL, address of the exit list. 
SYNAD=(ROUTNAME,L) 

ENDUP EODAD routine. 

LOGICAL LERAD routine. 

ROUTNAME DC C* PHYSICAL* Pad shorter names with 

blanks: C'SYN'or CL8'SYN ! 

The EXLST macro's parameters are: 

• EODAD specifies that the end-of-data routine is located at ENDUP and is 
not active. 
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• LERAD specifies that the logical error routine is located at LOGICAL and is 
active. 

• SYNAD specifies that the physical error routine's name is located at 
ROUTNAME. 



68 MVS/XA VSAM Administration: Macro Instruction Reference 



GENCB-ACB 



GENCB Macro (Generate an Access Method Control Block at 
Execution Time) 



The format of the GENCB macro used to generate an access method control 
block is: 



\label[ 



GENCB 



BLK = ACB 

|,AM = VSAM| 

lBSTRKO = number] 

|,BUFN1> = number] 

|,BUFNI = number] 

|,BUFSP = number] 

|,CATALOG=YES|NO| 

|,COPIES = number] 

|,CRA = SCRA|UCRA| 

|,DDN AME - ddname] 

|,EXLST = address] 

|,LENGTH- number] 

IXOC« BELOW ! ANY! 

|,M ACRE = (| ADR||,CNV||,KEY) 

|,CFX|NFX| 

L DDN IDSXI 

I.PFR1 NDF1 

|,DIR|I,SE(2||,SKP| 

I,ICI|NCI1 

|,IN||,OUT| 

I.NLSISIS1 

|,NRM|AIX| 

LNRSIRST1 

1,NSR|LSR|GSR] 

|,NlJBiUBF|)I 
1.MAREA-* address] 
|,MLEN = number] 
|,P ASSWD = address] 
[,RMODE31 = fALLlBUFFICBI NONEt l 
|,SHRPOOL= {0\number}] 
|,STRNO - number] 
|,WAREA = address] 



Note: The RMODE parameter replaces the AMODE31 subparamctcr used in 
previous releases. 

The subparametcrs of the GENCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that generate valid 
relocatable A-type address constants, in register notation, as S-type address 
constants, and as indirect S-type address constants. Appendix C, "Operand 
Notation" on page 181, further defines these operand expressions. 



label 



is 1 to 8 characters that provide a symbolic address for the GENCB macro. 
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BLK = ACB 

specifies that you are generating an access method control block. 

AM -VSAM 

specifies that the access method using this control block is VSAM. 

BSTRNO- rammer 

specifies the number of strings initially allocated for access to the base 
cluster of a path. The default is STRNO. BSTRNO is ignored if the 
object being opened is not a path. If the number specified for BSTRNO is 
insufficient, VSAM will dynamically extend the number of strings as needed 
for the access to the base cluster. BSTRNO can also influence 
performance. The VSAM control blocks for the set of strings specified by 
BSTRNO are allocated on contiguous virtual storage, whereas this is not 
guaranteed for the strings allocated by dynamic extension. 

BUFND = number 

specifics the number of I/O buffers VSAM is to use for transmitting data 
between virtual and auxiliary storage. A buffer is the size of a control 
interval in the data component. The minimum number you may specify is 
1 plus the number specified for STRNO (if you omit STRNO, BUFND 
must be at least 2, because the default for STRNO is I). The number can 
be supplied by way of the JCL DD AMP parameter as well as by way of 
the macro. The default is the minimum number required. A larger number 
for BUFND can improve the performance of sequential access. 

BUFNI = number 

specifies the number of I/O buffers VSAM is to use for transmitting index 
entries between virtual and auxiliary storage for keyed access. A buffer is 
the size of a control interval in the index. The minimum number is the 
number specified for STRNO (if you omit STRNO, BUFNI must be at 
least 1, because the default for STRNO is 1). You can supply the number 
by way of the JCL DD AMP parameter as well as by way of the macro. 
The default is the minimum number required. A larger number for BUFNI 
can improve the performance of keyed-direct retrieval. 

BUFSP = number 

specifies the maximum number of bytes of virtual storage to be used for the 
data and index I/O buffers. VSAM gets the storage in your program's 
address space. If you specify less than the amount of space that was 
specified in the BUFFERSPACE parameter of the DEFINE command 
when the data set was defined, VSAM overrides your BUFSP specification 
upward to the value specified in BUFFERSPACE. (BUFFERSPACE, by 
definition, is the least amount of virtual storage that will ever be provided 
for I/O buffers.) You can supply BUFSP by way of the JCL DD AMP 
parameter as well as by way of the macro. If you don't specify BUFSP in 
either place, the amount of storage used for buffer allocation is the largest 
of: 

• The amount specified in the catalog (BUFFERSPACE), 

* The amount determined from BUFND and BUFNI, or 
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• The minimum storage required to process the data set with its specified 
processing options 

If BUFSP is specified and the amount is smaller than the niinimum 
amount of storage required to process the data set, VSAM cannot open the 
data set. 

A valid BUFSP amount takes precedence over the amount called for by 
BUFND and BUFNI. If the BUFSP amount is greater than the amount 
called for by BUFND and BUFNI, the extra space is allocated as follows: 

• When MACRF indicates direct access only, additional index buffers are 
allocated. 

• When MACRF indicates sequential access, one additional index buffer 
and as many data buffers as possible are allocated. 

If the BUFSP amount is less than the amount called for by BUFND and 
BUFNI, the number of data and index buffers is decreased as follows: 

• When MACRF indicates direct access only, the number of data buffers 
is decreased to not less than the minimum number. Then, if required, 
the number of index buffers is decreased until the amount called for by 
BUFND and BUFNI complies with the BUFSP amount. 

• When MACRF indicates sequential access, the number of index buffers 
is decreased to not less than 1 more than the minimum number. Then, 
if required, the number of data buffers is decreased to not less than the 
minimum number. If still required, 1 more is subtracted from the 
number of index buffers. 

• Neither the number of data buffers nor the number of index buffers is 
decreased to less than the minimum number. 

If the index doesn't exist or isn't being opened, only BUFND, and not 
BUFNI, enters into these calculations. 

CATALOG = YES|NO 

specifics whether a catalog is being opened as a catalog (YFS) or as a data 
set (NO). When NO is coded (or taken as the default), you can process the 
catalog with request macros (GET, PUT, etc.). To open a 
password-protected catalog for processing with VSAM macros, you must 
supply its master password. When CATALOG = YFS is coded, the catalog 
must be processed with an SVC designed for that purpose. (Access method 
services, for example, processes catalogs with SVC 26.) The request macros 
are invalid for processing a catalog "as a catalog." VSAM users should alter 
the contents of a catalog only by access method services commands. 

-COPIES = number 

specifies the number of copies of the access method control block VSAM is 
to generate. All the copies are identical. You can use MODCB to tailor 
each one for the data set and processing you want for it. MODCB is 
described later in this chapter. 



Chapter 2. VSAM Macro Formats and Examples 71 



GENCB-ACB 



CRA = SCRA|UCRA 

specifies that a catalog recovery area is to be opened and that the control 
blocks are to be built in either system storage (SCR A) or user storage 
(UCRA). If you specify SCRA and issue record management requests, you 
must operate in key 0. If you specify UCRA, you must be authorized by 
the system and you must supply the master password of the master catalog. 

DDNAME = ddname 

is 1 to 8 characters that identify the data set that you want to process by 
specifying the JCL DD statement for the data set. You may omit 
DDNAME and provide it by way of the MODCB macro before opening 
the data set. MODCB is described later in this chapter. 

EXLST ■■ address 

specifics the address of a list of addresses of exit routines that you are 
providing. The list is established by the EXLST or GENCB macro. If you 
use the EXLST macro, you can specify its label here as the address of the 
exit list. If you use GENCB, you can specify the address returned by 
GENCB in register 1. Omitting this parameter indicates that you have no 
exit routines. Exit routines are described in the chapter "User- Written Exit 
Routines" in Data Facility Product: Customization. 

LENGTH- number 

specifies the length, in bytes, of the area, if any, that you are supplying for 
VSAM to generate the access method control block(s). (See the WAREA 
parameter.) When the LENGTH value is specified, it cannot exceed 65535 
(X'FFFF*). 

LOC=BELOW|ANY 

BELOW 

specifies that VSAM is to construct an ACB in an area of virtual 
storage below 16 megabytes at execution time. This is the default. 

ANY 

specifies that VSAM is to construct an ACB in an area of virtual 
storage above 16 megabytes, if possible, at execution time. 

MACRF = flAPRM.CNVM.KEYl 
I.CFXI NFX1 
I. PDN IDSNI 
I.DFRINDFI 
LDIRILSEQILSKPI 

[,iciincii 

I,IN|I,OUT| 

I.MSISISt 

I. NRM IA1XI 

I.NRSIRST1 

I.NSR1LSR1GSR1 

I,NUB|UBFD 
specifies the kind(s) of processing you will do with the data set. The 
subparameters must be meaningful for the data set. For example, if you 
specify keyed access for an entry-sequenced data set, you cannot open the 
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data set. You must specify all the types of access you're going to use, 
whether you use them concurrently or by switching from one to the other. 
The subparamcters are shown in Figure 12 on page 38. They are arranged 
in groups, and each group has a default value (indicated by underlining). 
You may specify subparameters in any order. You may specify both ADR 
and KEY to process a kcy-sequenccd data set. You may specify both DIR 
and SEQ; with keyed access, you may specify SKP as well. If you specify 
OUT and want merely to retrieve some records as well as update, delete, or 
insert others, you need not also specify IN. 

Note: The RMODE31 parameter replaces the AMODE31 subparamcter 
used in previous releases. 

MAREA ■» address 

specifies the address of an optional OPEN/CLOSE or TYPE = T option 
(CLOSE macro) message area. 

MLEN = number 

specifics the length of an optional OPEN/CLOSE or TYPE = T option 
(CLOSE macro) message area. 

PASSWD- address 

specifies the address of a field that contains the highest-level password 
required for the type(s) of access indicated by the MACRF parameter. The 
first byte of the field contains the length (in binary) of the password 
(maximum of 8 bytes). Zero indicates that no password is supplied. If the 
data set is password protected and you don't supply a required password in 
the access method control block, VSAM may give the console operator the 
opportunity to supply it when you open the data set. 

RMODE3! = IALLIBUFFICB1 NONEI 

specifies where VSAM OPEN is to obtain virtual storage (above or below 
16 megabytes) for control blocks and I/O buffers. 

The values specified by the RMODE31 parameter only have an effect on 
VSAM at the setting just before an OPEN is issued. At all other times, 
changing these values has no effect on the residency of the control blocks 
and I/O buffers. 

The virtual storage location of the ACB is independent of the RMODE31 
parameter. An ACB may reside cither above or below 16 megabytes. 

ALL 

both VSAM control blocks and I/O buffers are to be obtained above 
16 megabytes. 

BUFF 

only VSAM I/O buffers are to be obtained above 16 megabytes. 

CB 

only VSAM control blocks are to be obtained above 16 megabytes. 
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NONE 



both VSAM control blocks and I/O buffers are to be obtained below 
16 megabytes. This is the default. 

SHRPOOL«{m/mM0} 

specifics the identification number of the resource pool to be used for LSR 
processing. The default is SHRPOOL=0. 

STRNO = number 

specifics the number of requests requiring concurrent data set positioning 
VSAM is to be prepared to handle. A request is defined by a given request 
parameter list or chain of request parameter lists. See "RPL Macro 
(Generate a Request Parameter List at Assembly Time)" on page 126 and 
"GENCB Macro (Generate a Request Parameter List at Execution Time)" 
on page 80 for information on request parameter lists. 

W ARE A - address 

specifics the address of an area in which to generate the access method 
control block(s). 

The area must begin oh a fullword boundary. 

This parameter is paired with the LENGTH parameter. You must supply 
the LENGTH parameter if you specify an area address. 

Note: If you do not specify an area in which the access method control 
block is to be generated, VSAM obtains virtual storage space for the area 
(as specified by the LOC = keyword). VSAM returns the address of the 
area containing the control block(s) in register 1 and the length of the area 
in register 0. You can find out the length of each control block by dividing 
the length of the area by the number of copies. The address of each control 
block can then be calculated by this offset from the address in register 1. 
You can find the length of an access method control block with the 
SHOWCB macro. 

If you are generating control blocks by issuing several GENCBs, specifying 
an area (WAREA and LENGTH parameters) for them enables you to 
address all of them with one base register and to avoid repetitive requests 
for virtual storage. 
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Example: GENCB JMacro (Generate an Access Method Control Block) 



In this example, a GENCB macro is used to identify a data set to be opened and 
to specify the types of processing to be performed. This example specifics that 
the space for the control block be obtained above 16 megabytes. The access 
method control block generated by this example is built when the program is 
executed. 

GENCB GENCB BLK=ACB,AM=VSAM, One copy generated; VSAM 

BUFND=4,BUFNI=3, gets the storage for it, 

BUFSP=19456, because the WAREA LENGTH 

DDNAME=DATASETS, parameters have been 



ST 



ACBADDR DS 



FIELD 



DC 



EXLST=EXITS, 

LOC=ANY, 

MACRF=(KEY,DIR, 

SEQ,OUT), 

PASSWD=FIELD, 

RM0DE31=ALL, 

STRN0=2 

1, ACBADDR 



omitted. 



Save the address of the 
access method control 
block. 

The address of the 
access method control 
block is saved in 
ACBADDR. 



FLlV.C* CHANGE' CHANGE, the password, has 
6 characters. 



The GENCB macro's parameters are: 

• BUFND specifics four I/O buffers for data; BUFNI specifics three I/O 
buffers for index entries; and BUFSP specifics 19456 bytes of buffer space, 
enough space to accommodate control intervals of data that are 4096 bytes 
and of index entries that are 1024 bytes. 

• DDNAME specifies that this access method control block is associated with 
a DD statement named DATASETS. 

• EXLST specifics that the exit list associated with this access method control 
block is named EXITS. 

• LOC specifics that VSAM obtain virtual storage for the ACB from an area 
that may be above 16 megabytes. 

• MACRF specifies keyed direct and keyed sequential processing for both 
insertion and update. 

• PASSVVD specifies the location, FIELD, of the password provided. 

• RMODE31 specifies that VSAM obtain storage for the VSAM control 
blocks and I/O buffers in an area above 16 megabytes when the ACB is 
opened. 

• STRNO specifies that two requests will require concurrent positioning. 
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GENCB Macro (Generate an Exit List at Execution Time) 

The format of the GENCB macro used to generate an exit list is: 



[label\ 


GENCB 


BLK = EXLST 
LAM-VSAMl 

I,EODAD - (address[,A\X\m)\ 
IJRNAD - («/<4reu|,A|N||,L|)| 
(,LERAD - (address\,A\X\lL[)\ 
I,SYNAD - (<utfretf|,A|N||,L|)| 
|,COPIES- number] ~ 
|,LENGTH = number] 
|,LOC = BELOW|ANY| 
\,WAREA» address] 



The parameters of the GENCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that generate valid 
relocatable A-type address constants, in register notation, as S-type address 
constants, and as indirect S-type address constants. Appendix C, "Operand 
Notation" on page 181, further defines these operand expressions. 

Note: See Data Facility Product: Customization for the factors that determine 
the addressing mode and the parameter list residency mode set when the exit 
routine gets control. 

label 

is 1 to 8 characters that provide a symbolic address for the GENCB macro. 

BLK = EXLST 

specifies that you are generating an exit list. 

AM - VSAM 

specifies that the access method using this control block is VSAM. 

[,EODAD - (arf</mjf,A|NH,L|)l 
I^JRNAD = (a<fc/rett|,A|NH,L|)| 
(,LERAD - (address\ t A\MM)\ 
1.SYNAD - (arfdtexs|,A|N||,L|)| 

specify that you are supplying a routine for the exit named. 

For more information about user exit routines, see Data Facility Product: 
Customization. 

If none of these user exit routines is specified, VSAM generates an exit list 
with inactive entries for all the exits. The exits and values that can be 
specified for them are: 

EODAD 

specifies that an exit is provided for special processing when the end 
of a data set is reached by sequential access. 



76 MVS/XA VSAM Administration: Macro Instruction Reference 



GENCB-EXLST 



JRNAD 



specifies that an exit is provided for joumaling as you process data 
records. 

LERAD 

specifies that an exit is provided for analyzing logical errors. 

SYNAD 

specifics that an exit is provided for analyzing physical errors. 

address 

is the address of a user-supplied exit routine. Trie address must 
immediately follow the equal sign. 



A|N 



specifies that the exit routine is active (A) or not active (N). VSAM 
does not enter a routine whose exit is marked not active. 



specifics that the address is that of an 8-byte field that contains the 
name of an exit routine in a partitioned data set that is identified by a 
JOBLIB or STEPLIB DD statement or in SYS1.LINKLIB. VSAM 
is to load the exit routine for exit processing. If L is omitted, the 
address gives the entry point of the exit routine in virtual storage, and 
the exit routine is entered in the addressing mode of the VSAM caller. 
L may precede or follow the A or N specification. 

COPIES = number 

specifies the number of copies of the exit list you want generated. GENCB 
generates as many copies as you specify (default is 1) when your program is 
executed. All copies are the same. You can use MODCB to change some 
or all of the addresses in a list. (MODCB is described later in this chapter.) 

LENGTH = number 

specifies the length, in bytes, of the area, if any, that you are supplying for 
VSAM to generate the exit list(s). (See the WAREA parameter.) When 
the LENGTH value is specified, it cannot exceed 65535 (X f FFFF ' ). 

LOC = BELOW|ANY 

BELOW 

specifics that VSAM is to construct an exit list in an area below 16 
megabytes at execution time. This is the default value. 

ANY 

specifics that VSAM is to construct an exit list in an area above 16 
megabytes, if possible, at execution time. 

WAREA '-address 

specifies the address of an area in which the exit list(s) is to be generated. 

The area must begin on a fullword boundary. 
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This parameter is paired with the LENGTH parameter, which must be 
given if you specify an area address. 

Note: If you did not specify an area in which the exit list is to be 
generated, VSAM obtains virtual storage space for the area (as specified by 
the LOC = keyword). VSAM returns the address of the area in which the 
exit lists(s) is to be generated in register 1, and the length of the area in 
register 0. You can find the length of each exit list by dividing the length of 
the area by the number of copies. The address of each exit list can then be 
calculated by this offset from the address in register 1. You can find the 
length of an exit list with the SHOVVCB macro, described under 
"SHOWCB Macro (Display Fields of an Exit List)" on page 139. 

If you arc generating control blocks by issuing several GENCBs, specifying 
an area (WAREA and LENGTH) for them enables you to address all of 
them with one base register and to avoid repetitive requests for virtual 
storage. 



Example: GENCB Macro (Generate an Exit List) 



In this example, a GENCB macro is used to generate an exit list when the 
program is executed. 



EXITS 


GENCB 


BLK=EXLST, 
E0BAD=<E0D,N), 
LERAD=LOGICAL, 
SYNAD=( ERROR, 
A,L) 




LTR 


15,15 




BNZ 


ERROR 




ST 


1, EXLSTADR 


EOD 


EQU 


* 


LOGICAL 


EQU 


* 


ERROR 


DC 


C' PHYSICAL* 


EXLSTADR 


DS 


F 



Address of the exit list is saved. 

EODAD routine. 

LERAD routine. 

Name of the SYNAD module. 

Save area for exit- list address. 



The GENCB macro's parameters arc: 

• BLK specifies that an exit list is to be generated. 

• EODAD specifics that the end-of-data routine is located at EOD and is not 
active. 

• LERAD specifies that the logical error routine is located at LOGICAL; 
because neither A nor N is specified, the LERAD routine is marked active by 
default. 

• SYNAD specifies that the physical error routine's name is located at 
ERROR. 
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Because no area was specified in which the exit list was to be generated, VSAM 
obtained virtual storage for the exit list and returned the address in register 1. 
Immediately after the GENCB macro, the address of the exit list, contained in 
register 1, is moved to EXLSTADR. EXLSTADR may be specified in a 
GENCB macro that generates an access method control block or in a MODCB, 
SHO WCB, or TESTCB macro that modifies, displays, or tests fields in an exit 
list. 
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GENCB Macro (Generate a Request Parameter List at Execution 
Time) 

The format of the GENCB macro used to generate a request parameter list is: 



[label] 


GENCB 


BLK = RPL 
[,ACB = address] 
UM~VSAM| 
\, ARE A = address] 
],AREALEN = number] 
|,ARG = address] 
(,COPIES- number] 
(,ECB =» address] 
|,KEYLEN = number] 
|,LENGTH = number] 
|,LOC = BELOW|ANYI 
|,MSGAREA - address] 
],MSGLEN = number] 
|,NXTRPL = address] 
|,OP TCD » (|ADR|CNV| KEY| 
IJMRISEQISKPI 






l,ARI*tLR»l 
|,F\VD|BWD| 
|,ASY|SYN| 
|,NSP|NUP|UPD| 
|,KKg|KGK| 
|,FKS|GEN| 
|,LOC|MVEl)| 
IRECLEN- number] 
[,TRANSID = number] 
[ y W ARE A = address] 



The parameters of the GENCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that generate valid 
relocatable A-type address constants, in register notation, as S-type address 
constants, and as indirect S-type address constants. Appendix C, "Operand 
Notation" on page 181 further defines these operand expressions. 

The parameters of the GENCB macro to generate a request parameter list are 
optional in some cases, but required in others. It is not necessary to omit 
parameters that are not required for a request; they arc ignored. Thus, for 
example, if you switch from direct to sequential retrieval with a request parameter 
list, you don't have to zero out the address of the field containing the search 
argument (ARG = address). 



label 



is 1 to 8 characters that provide a symbolic address for the GENCB macro. 
For addressing lists generated by GENCB, see the discussion of the 
COPIES parameter. 
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BLK = RPL 

specifies that you are generating a request parameter list. 

ACB = address 

specifies the address of the access method control block that identifies the 
data set to which access will be requested. If you omit this parameter, you 
must issue MODCB to specify the address of the access method control 
block before you issue a request. (MODCB is described later in this 
chapter.) 

AM = VSAM 

specifies that the access method using this control block is VSAM. 

AREA = address 

specifics the address of a work area to and from which VSAM moves a data 
record if you request it to do so (with the RPL parameter 
OPTCD= MVE). If you request that records be processed in the I/O 
buffer (OPTCD= LOC), VSAM puts into this work area the address of a 
data record within the I/O buffer. 

AREALEN = number 

specifics the length, in bytes, of the work area whose address is specified by 
the AREA parameter. Its minimum for OPTCD= MVE is the size of a 
data record (or the largest data record, for a data set with records of variable 
length). For OPTCD= LOC, the area should be 4 bytes to contain the 
address of a data record within the I/O buffer. 

ARC - address 

specifics the address of a field that contains the search argument for direct 
retrieval, skip-sequential retrieval, and positioning. For a relative record 
data set, the ARG field must be 4 bytes long. For direct or skip-sequential 
processing, this field contains your search argument, a relative record 
number. For sequential processing (OPTCD = (KEY.SEQ)), the 4 bytes 
arc required for VSAM to return theieedbaek URN. For keyed access 
(OPTCD= KEY), the search argument is a full or generic key; for 
addressed access (OPTCD = ADR), it is an RBA. If you specify a generic 
key (OPTCD = GEN), you must also specify in the KEYLEN parameter 
how many of the bytes of the full key you are using for the generic key. 

COPIES = number 

specifics the number of copies of the request parameter list you want 
generated. GENCB generates as many copies as you specify (default is 1) 
when your program is executed. 

The copies of a request parameter list can be used to: 

• Chain lists together to gain access to many records with one request 

• Define many requests to gain access to many parts of a data set 
concurrently 

All copies generated are identical; you must use MODCB to tailor them to 
specific requests. MODCB is described in this chapter. 
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ECB = address 

specifies the address of an event control block (ECB) that you may supply. 
VSAiM indicates in the ECB whether a request is complete or not (using 
standard completion codes, which are described in Data Areas). You can 
use the ECB to determine that an asynchronous request is complete before 
issuing a CHECK macro. This parameter is always optional. 

KEYLEN = number 

specifies the length, in bytes, of the generic key (OPTCD = GEN) you are 
using for a search argument (given in the field addressed by the ARG 
parameter). This parameter is required with a search argument that is a 
generic key. The number can be 1 through 255. For full-key searches, 
VSAM knows the key length, which is taken from the catalog definition of 
the data set when you open the data set. 

LENGTH = number 

specifies the length, in bytes, of the area, if any, that you arc supplying for 
VSAM to generate the request parameter list(s). (Sec the WAREA 
parameter.) When the LENGTH value is specified, it cannot exceed 65535 
(X'FFFF '). 

You can find out how long a request parameter list is with the SIIOWCB 
macro, described later in this chapter. 

LOC = BELOW|ANY 

BELOW 

specifics that storage for the RPL be obtained from virtual storage 
below 16 megabytes. This is the default value. 

ANY 

specifics that storage be obtained from virtual storage above 16 
megabytes if possible. 

MSGAREA = address 

specifies the address of an area that you are supplying for VSAM to send 
you a message in case of a physical error. (The format of a physical error 
message is given under "Physical Errors" in the chapter "Request 
Macros.") 

MSGLEN = number 

specifies the size, in bytes, of the message area indicated in the MSGAREA 
parameter. The size of a message is 128 bytes; if you provide less than 128 
bytes, no message is returned to your program. This parameter is required 
when MSGAREA is coded. 
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KXTRPL~ address 

specifies the address of the next request parameter list in a chain. Omit this 
parameter from the macro that generates the only or last list in the chain. 
When you issue a request that is defined by a chain of request parameter 
lists, indicate in the request macro the address of the first parameter list in 
the chain. A single request macro can be defined by multiple request 
parameter lists, such that a GET, for example, can cause VSAM to retrieve 
two or more records. 

OPTCD = (1ADRICNVI KEY1 
|,DIR|SEQ|SKP| 
I. ARD 1LRD1 
• I. FWD IBWDI 
I.ASYI SYNI 
|,NSP1 NUP |UPD| 
IJKEQIKGEI 
I.FKSIGEM 
IXOCI MVEI) 

specifies the subparamctcrs that govern the request defined by the request, 
parameter list. Each group of subparameters has a default; subparameters 
arc shown in Figure 13 on page 128 with defaults underlined. Only one 
subparamctcr from each group is effective for a request. Some requests do 
not require an subparamctcr from all of the groups to be specified. The 
groups that are not required are ignored; thus, you can use the same request 
parameter list for a combination of requests (GET, PUT, POINT, for 
example) without zeroing out the inapplicable subparameters each time you 
go from one request to another. 

RECLEN- number 

specifies the length, in bytes, of a data record being stored. If the records 
you are storing are all the same length, you will not need to change 
RECLEN after you set it. This parameter is required for PUT requests. 
For GET requests, VSAM puts the length of the record retrieved in this 
field in the request parameter list. It will he there If you update and store 
the record. 

TRANSID- number 

specifics a number that relates modified buffers in a buffer pool. Use in 
shared resource applications and a description are in "Sharing Resources" 
in VSAM Administration Guide. 

WAREA- address 

specifics the address of an area in which the request parameter list(s) is to 
be generated. 

The area must begin on a fullword boundary. 

This parameter is paired with the LENGTH parameter, which must be 
given if you specify an area address. 

Note: If you did not specify an area in which the request parameter list is 
to be generated, VSAM obtains virtual storage space for the area (as 
specified by the LOC = keyword). VSAM returns the address of the area in 
which the request parameter list(s) is generated in register 1, and the length 
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of the area in register 0. You can find the length of each list by dividing the 
length of the area by the number of copies. You can then calculate the 
address of each list by using the length of each list as an offset. 

If you are generating control blocks by issuing several GENCBs, specifying 
an area (WAREA and LENGTH parameters) for them enables you to 
address all of them with one base register and to avoid repetitive requests 
for virtual storage. 



Building a Chain of Request Parameter Lists 



GENCB 


BLK=RPL 


LR 


2,1 


GENCB 


BLK=RPL, NXTRPL=( 2 ) 



When GENCB is used to build a chain of request parameter lists, the request 
parameter lists may be chained using only GENCB macros or using GENCB and 
MODCB macros together. When only GENCB is used, the request parameter 
lists are created in reverse order, as follows: 

SECOND 

FIRST 

SECOND GENCB creates the second request parameter list, which makes its 
address available for the first request parameter list. The address of the request 
parameter list is returned in register 1 and is loaded into register 2. FIRST 
GENCB creates the first request parameter list and supplies the address of the 
next request parameter fist using register notation. GENCB ancf MODCB" 
macros may be used together to create a chain of request parameter lists, as 
follows: 



GENCB 


BLK=RPL,C0PIES=2 


LR 


2,0 


SRL 


2,1 


LR 


3,1 


LA 


4,0(2,3) 


MODCB 


RPL=(3),NXTRPL=(4) 



The GENCB macro creates two request parameter lists. The length of the 
parameter lists is returned in register and loaded into register 2. The address of 
the area in which the lists were created (and, therefore, the address of the first 
one) is returned in register 1 and loaded into register 3. The SRL statement 
divides the total length of the area (register 2) by 2. The LA statement loads the 
address of the second request parameter list into register 4. The MODCB macro 
modifies the first request parameter list (register 3) by supplying the address of the 
second request parameter list (register 4) in the NXTRPL parameter. 

Each request parameter list in a chain should have the same OPTCD 
subparameters. Having different subparameters may cause logical errors. You 
can't chain request parameter lists for updating or deleting records— only for 
retrieving records or storing new records. You can't process records in the I/O 
buffer with chained request parameter lists. (OPTCD = UPD and LOC are 
invalid for chained request parameter lists.) 



84 MVS/XA VSAM Administration: Macro Instruction Reference 



GENCB-RPL 

Example: GENCB Macro (Generate a Request Parameter List) 

In this example, a GENCB macro is used to generate a request parameter list. 

ACCESS GENCB BLK=RPL, 

ACB=ACCESS, 

AM=VSAM, 

AREA=WORK, 

AREALEN=125, 

ARG=SEARCH, 

LOC=ANY, 

MSGAREA=MESSAGE, 

MSGLEN=128, 

OPTCD=(SKP,UPD) 

ACCESS ACB MACRF=(SKP,OUT) 

WORK DS CL125 

SEARCH DS CL8 

MESSAGE DS CL128 

The GENCB macro's parameters are: 

BLK specifics that a request parameter list is to be generated. 

ACB specifies that the request parameter list is associated with a data set and 
processing options identified by ACCESS. 

AREA and AREALEN specify a 125-byte work area to be used for 
processing records. 

ARG specifies the address of the search argument. 

LOC specifics that VSAM obtain storage for the request parameter list in an 
area above 16 megabytes. 

MSGAREA and MSGLEN specify a 128-byte area to be used for 
physical-error messages. 

OPTCD specifies the subparametcrs that govern the request defined by the 
request parameter list identified by SKP and UPD. 
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GET Macro (Retrieve a Record) 



The format of the GET macro is: 



\label\ 


GET 


RPI = address 



where: 



label 

is 1 to 8 characters that provide a symbolic address for the GET macro. 

RPL = address 

specifics the address of the request parameter list that defines this GET 
request. You may specify the address in register notation (using a register 
from 1 through 12, enclosed in parentheses) or specify it with an expression 
that generates a valid relocatable A-type address constant. 



Example 1: Keyed- Sequential Retrieval (Forward) 



In this example, a GET macro is used to sequentially retrieve records by key. 
Retrieval is in a forward direction. Fixed-length, 100-byte records are moved to a 
work area. Processing^ synchronous. 



INPUT ACB 



RETRVE RPL 



MACRF=(KEY, 
SEQ,IN) 



ACB=INPUT, 

AREA=IN, 

AREALEN=100, 

OPTCD=(KEY,SEQ, 

SYN,NUP,MVE) 



All MACRF and OPTCD 
subparameters specified are 
defaults and could have 
been omitted. 



LOOP GET RPL=RETRVE 

LTR 15,15 
BNZ ERROR 



This GET or identical GETs can 
be issued, with no change in 
the request parameter list, to 
retrieve subsequent records in 
key sequence. 



ERROR 



LOOP 



Request was not accepted, or 
failed. 



IN 



DS CL100 



IN contains a data record after 
GET is completed. 



The records are retrieved in key sequence in a forward direction. No search 
argument has to be specified; VSAM is positioned at the first record in key 
sequence when the data set is opened, and the next record is retrieved 
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automatically as each GET is issued. The branch to ERROR could also be 
taken if the end of the data set is reached. 



Example 2: Keyed-Sequential Retrieval (Backward) 



This example is the same as the previous one, except that a POINT macro 
instruction is issued to the last record in the data set and the records are retrieved 
in a backward direction. 



Define RPL for last record 
positioning and backward 
processing. 



INPUT 


ACB 


DDNAME=INPUT, 
EXLST=EXLST1 


RETRVE 


RPL 


ACB=INPUT, 

AREA=IN, 

AREALEN=100, 

OPTCD=(KEY,SEQ, 

LRD,BWD) 


EXLST1 


EXLST 


EODAD=EOD 




POINT 


RPL=RETRVE 




LTR 


15,15 




BNZ 


ERROR 


LOOP 


GET 


RPL=RETRVE 




LTR 


15,15 




BNZ 


ERROR 




B 


LOOP 


EOD 


EQU 


* 


ERROR 







Define end of data. 

Position to last record (no 
argument is required). 



Get previous record. 



Come here for end of data, 
Request failed. 



IN 



DS 



CL100 



Area for retrieved record. 



Example 3: Skip-Sequential Retrieval 



In this example, a GET macro is used to retrieve variable-length records 
synchronously. Records are to be processed in the I/O buffer. The search 
argument is full key, compared greatcr-than-or-equal; key length is eight bytes. 

The records are retrieved in key sequence, but some records arc skipped. 
Skip-sequential retrieval is similar to keyed-direct retrieval, except that you must 
retrieve records in ascending sequence (with skips) rather than in a random 
sequence. 



GENCB BLK=ACB, 

DDNAME=INPUT, 

MACRF=(KEY, 

SKP,IN) 



LTR 15,15 



VSAM gets an area in 
virtual storage to generate 
the access method control 
block and returns the 
address in register 1. 
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BNZ 


CHECKO 


LR 


2,1 


GENCB 


BLK=RPL, 

ACB=(2), 

AREA=RCDADDR, 

AREALEN=4, 

ARG=SRCHKEY, 

OPTCD=(KEY,SKP, 

SYN,NUP,KGE, 

FKS,LOC) 


LTR 


15,15 


BNZ 


CHECKO 


LR 


3,1 



Address of the request 
parameter list. 



LOOP 



MVC 



SRCHKEY, source 



GET RPL=(3) 

LTR 15,15 

BNZ ERROR 

SHOWCB AREA=RCDLEN, 

FIELDS=RECLEN, 

LENGTH=4, 

RPL=(3) 

LTR 15,15 

BNZ CHECKO 



Search argument for 
retrieval, moved in from 
a table or a transaction 
record. 



Display the length of the 
record. 



ERROR 



CHECKO 



LOOP 



Request was not accepted, 
or failed. 

Generation or display 
failed. 



RCDADDR DS 

SRCHKEY DS 
RCDLEN DS 



CL8 
F 



Work area into which VSAM puts 
the address of a data record 
within the I/O buffer 
(OPTCD=LOC). 

Search argument for retrieval. 

For displaying variable record 
lengths. 



The macros and instructions are as follows: 
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• The first GENCB generates an access method control block, which specifies 
keyed, skip-sequential, and input processing. The address of the access 
method control block is stored in register 2. 

• The second GENCB generates a request parameter list. The address of the 
request parameter list is stored in register 3. 

• MVC moves the search argument into SRCHKEY, the area defined for the 
search argument. 

• GET specifies that the record pointed at by the request parameter list whose 
address is in register 3 is to be retrieved. Records are retrieved by a 
skip-sequential search through the sequence set of the index. 



Example 4: Addrcsscd-Scqucntial Retrieval 



In this example, one GET macro is used to retrieve multiple fixed-length, 20-byte 
records. The records are moved to a work area (only option). 



BLOCK ACB 


DDNAME=INPUT, 

MACRF=(ADR,SEQ, 

IN) 


GENCB 


BLK=RPL, 

COPIES=10, 

ACB=BLOCK, 

OPTCD=(ADR,SEQ, 

SYN,NUP,MVE) 


LTR 


15,15 


BNZ 


CHECKO 


LA 


3,10 


LR 


2,1 


LR 


1,0 



SR 
DR 

LR 

LR 
LA 



0,0 
0,3 

3,1 

4,2 
5,RECAREA 



Number of lists (10). 

Address of the first list. 

Length of all of the lists. 
Registers and 1 contain 
length and address of the 
generated control blocks 
when VSAM returns control 
after GENCB. 
Prepare for following division. 

Divide number of lists into 
length of all the lists. 

Save the resulting length of a 
single list for an offset. 

Save address of the first 

list. 

Address of the first work 

area. 

Do the following 6 

instructions 10 times to set 

up all the request parameters 

lists. The 10th time, register 

4 must be set to to indicate 

the last request parameter 

list in the chain. 
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AR 


4,3 


MODCB 


RPL=(2), 
NXTRPL=(4), 
AREA=(5), 
AREALEN=20 


LTR 


15,15 


BNZ 


CHECKO 


AR 


2,3 


LA 


5,20(5) 



Address the next list. 

In each request parameter list, 
indicate the address of the 
next list and the address and 
length of the work area. 



Address the next list. 

Address the next work area. 
Restore register 2 to address 
the first list before continuing 
to orocess. 



LOOP 


GET 


RPL=(2) 






LTR 


15,15 






BNZ 


ERROR 


Process the 10 records that 
have been retrieved by the 
GET. 




B 


LOOP 




CHECKO 








ERROR 






Display the feedback field 



RECAREA DS CL200 



(FIELDS=FDBK) of each request 
parameter list to find out 
which one had an error. 

Space for a work area for each 
of the 10 request parameter 
lists. 



The GENCB macro generates 10 request parameter lists; the lists are 
subsequently chained together by using the MODCB macro to modify the 
NXTRPL parameter in each copy. Because SEQ is specified in each request 
parameter list and no previous request has been issued against the access method 
control block since it was opened, retrieval begins at the beginning of the data set. 
Each time the GET macro is executed, VSAM is positioned at the next record in 
RBA sequence. VSAM moves each record into the work area provided for the 
request parameter list that identifies the record. 

If an error occurred for one of the request parameter lists in the chain and you 
have supplied error-analysis routines, VSAM takes a LERAD or SYNAD exit 
before returning to your program. Register 15 is set to indicate the status of the 
request. A code of indicates that no error was associated with any of the 
request parameter lists. Any other code indicates that an error occurred for one 
of the request parameter lists. You should issue a SHOWCB macro for each 
request parameter list in the chain to find out which had an error. VSAM 
doesn't process any of the request parameter lists except the one with an error. 
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Example 5: Sequential Retrieval for a Relative Record Data Set 



In this example, a GET macro is used to sequentially retrieve records by relative 
record number. Fixed-length, 100-byte records are moved to a work area. 
Processing is synchronous. 



INPUT 



ACB 



RETRVE RPL 



MACRF=(KEY,SEQ, 
IN) 



ACB=INPUT, 

AREA=IN, 

AREALEN=100, 

ARG=RCDNO, 

OPTCD=(KEY,SEQ, 

SNY,NUP,MVE) 



All MACRF and OPTCD 
subparameters specified are 
defaults and could have been 
omitted. 



LOOP GET RPL=RETRVE 



LTR 15,15 
BNZ ERROR 



This GET or identical GETs 
can be issued, with no change 
in the RPL, to retrieve 
subsequent records in relative 
record number sequence. 



ERROR 



LOOP 



Request was not accepted or 
it failed. 



IN 



RCDNO 



DS CL100 



DS CL4 



IN contains a data record 
after GET is ^xmplBtMd- 

VSAM returns relative record 
number of retrieved record in 
this field. 



The records arc retrieved in relative record number sequence. Empty records are 
bypassed for sequential retrieval. A 4-bytc search argument must be specified. 
The relative record number of each record retrieved is stored in the search 
argument. VSAM is positioned at the first relative record when the data set is 
opened, and the next nonempty record is retrieved automatically as each GET is 
issued. The branch to ERROR would also be taken if the end of the data set is 
reached. 
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Example 6: Keyed-Direct Retrieval 



In this example, a GET macro is used to retrieve fixed-length, 100-byte records 
directly by key. The key length is 15 bytes; the search argument is a 5-byte 
generic key, compared equal. The control blocks are generated at assembly. 



INPUT ACB 



RETRVE RPL 



MACRF=(KEY, 
DIR,IN) 

ACB=INPUT, 

AREA=IN, 

AREALEN=4, 

OPTCD=(KEY, 

DIR,SYN,NUP, 

KEQ,GEN,LOC), 

ARG=KEYAREA, 

KEYLEN=5 



You specify all parameters for 
the request in the RPL macro. 



LOOP MVC KEYAREA, SOURCE 



GET RPL=RETRVE 



LTK 15,15 
BNZ ERROR 



Search argument for retrieval, 
moved in from a table or a 
transaction record. 

This GET or identical GETs can 
be issued with no change in the 
RPL: Specify each new search 
argument in the field KEYAREA. 



Process the record. 



ERROR 



LOOP 



Request was not accepted, or 
failed. 



IN 



DS CL4 



KEYAREA DS CL5 



VSAM puts here the address of 
the record within the I/O 
buffer. 

You specify the search argument 
here. 



The generic key specifics a class of records. For example, if you search on the 
first third of employee number, VSAM positions at and retrieves the first of 
presumably several records that start with the specified characters. To retrieve all 
the records in that class, either switch to sequential access or to a full-key search 
with a greater-than-or-cqual comparison. 
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Example 7: Addrcsscd-Direct Retrieval 



In this example, a GET macro is used to retrieve fixed-length 20-byte records. 
The records are to be moved to a work area. 

BLOCK ACB DDNAME=INPUT, Access method control 
MACRF=(ADR, DIR, block generated at 
IN) assembly. 



GENCB BLK=RPL, 
C0PIES=1, 
ACB=BLOCK, 
OPTCD=(ADR, DIR, 
SYN, NUP, MVE) 

LTR 15,15 

BNZ CHECKO 

LR 2, 1 



ARG=SRCHADR, AREA=IN, 

AREALEN=20 

Request parameter list 

generated at execution. 



Address of the list. 



LOOP 



MVC 

GET 
LTR 
BNZ 



SRCHADR, 

RPL=(2) 
15, 15 
ERROR 



Search argument for 
retrieval; calculated or 
moved in from a table or 
a transaction record. 



Process the record. 



CHECKO 
ERROR 



LOOP 



Generation failed. 

Request was not accepted, 
or failed. 



IN 



DS 



CL20 



VSAM puts a record here 
for each GET request. 



SRCHADR DS 



CL4 



You specify the RBA 
search argument here for 
each request. 



The RBA provided for a search argument must match the RBA of a record. 
Keyed insertion and deletion of records in a key-sequenced data set will probably 
cause the RBAs of some records to change. Therefore, if you process a 
key-sequenced data set by addressed-direct access (or by addressed-sequential 
access using POINT), you need to keep track of changes. You can use the 
JRNAD exit for this purpose. See "EXLST Macro (Generate an Exit List at 
Assembly Time)" on page 66. 



Chapter 2. VSAM Macro Formats and Examples 93 



GET 



Example 8: Switch from Direct to Sequential Retrieval 



In this example, GET macros are used to retrieve fixed-length, 100-byte records. 
The retrieval is via an alternate index path defined with the nonunique key 
option. Every time a nonunique key is retrieved, the program switches to 
sequential processing to retrieve the other records with the same key. The 
control blocks were generated at assembly, but the MODCB macro is used to 
modify the request parameter list to permit switching from keyed-direct to 
keyed-sequential retrieval. For the direct request preceding sequential requests, 
the search argument is an 8-byte, generic key, compared equal. Positioning is 
requested for direct requests. 

Both direct and 
sequential access 
specified. 

NSP specifies that VSAM 
is to remember its 
position. 



INPUT 


ACB 


MACRF=(KEY,DIR, 
SEQ,IN) 


RETRVE 


RPL 


ACB=INPUT, 

AREA=IN, 

AREALEN=100, 

0PTCD=(KEY,DIR, 

SYN,NSP,KEQ, 

GENEVE), 

ARG=KEYAREA, 

KEYLEN=£ 


LOOP 


MV€ 


KEYAREA, source 


L00P1 


GET 


RPL=RETRVE 




LTR 


15,15 




BNZ 


ERROR 




SHOWCB 


RPL=RETRVE, 

AREA=FDBAREA, 

FIELDS=FDBK 




LTR 


15,15 




BNZ 


ERROR 




CLI 


ERRCD,8 




BE 


SEQ 




B 


LOOP 



SEQ 



MODCB RPL=RETRVE, 
OPTCD=SEQ 



LTR 15,15 
BNZ CHECKO 



Search argument for 
direct retrieval; moved 
in from a table or a 
transaction record. 



Extract feedback 
information. 



Does a duplicate key 
follow? 

Yes; retrieve duplicates 
sequentially. 

No; retrieve next record 
in direct mode. 

Alter request parameter 
list for sequential 
access. 
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SEQGET 


GET 


RPL=RETRVE 




LTR 


15,15 




BNZ 


ERROR 




SHOWCB 


RPL=RETRVE, 

AREA=FDBAREA, 

FIELDS=FDBK 



Do sequential retrieval. 
Test for error. 



Extract feedback 
information. 



LTR 15,15 
BNZ ERROR 
CLI ERRCD,8 



DIR 



ERROR 



CKECKC 



Does a duplicate key 
follow? 



BE 


SEQGET 


Yes ; retrieve 
sequentially. 


MODCB 


RPL=RETRVE, 
OPTCD=DIR 


Alter request parameter 
list for direct access. 


LTR 


15,15 




BNZ 


CHECKO 




B 


LOOP 


Prepare new search 
argument . 






Request was not accepted, 
or failed. 



tfodification failed. 



VSAM puts retrieved 
records here. 

Specify the generic key 
for a direct request 
here. 

Feedback area for SHOWCB 

Reserved. 

Error type code. 

Component code. 

Reason code. 



Positioning is associated with a request parameter list; the MODCB macro is 
used to modify a single request parameter list that alternately defines requests for 
both types of access rather than use a different request parameter list for each 
type. 

With direct retrieval, VSAM doesn't remember its position for subsequent 
sequential retrieval unless you explicitly request it (OPTCD= NSP or UPD). 
After a direct GET for update, VSAM is positioned for a subsequent PUT, 



IN 


DS 


CL100 


KEYAREA 


DS 


CL8 


FDBAREA 


DS 


OF 




DS 


1C 


TYPECD 


DS 


1C 


CMPCD 


DS 


1C 


ERRCD 


DS 


1C 
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ERASE, or sequential GET. If you modify OPTCD= (DIR.NUP) to 
OPTCD=SEQ, you must issue POINT to get VSAM positioned for sequential 
retrieval, as NUP indicates that no positioning is desired with a direct GET. 

If you have chained many request parameter lists together, one position is 
remembered for the whole chain. For example, if you issue a GET that gives the 
address of the first request parameter list in the chain, the position of VSAM 
when the GET request is complete is at the record following the record defined 
by the last request parameter list in the chain. Therefore, modifying 
OFrCD = (DIR,NSP) in each request parameter list in a chain to 
OPTCD = SEQ implies continuing with sequential access relative to the last of 
the direct request parameter lists. 
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GETIX Macro (Retrieve an Index Record) 

The format of the GETIX macro is: 



\Iabel\ 


GETIX 


RPL = address 



where: 

label 

is 1 to 8 characters that provide a symbolic address for the GETIX macro. 

RPL = address 

specifies the address of the request parameter list that defines this GETIX 
request. You may specify the address in register notation (using a register 
from 1 through 12, enclosed in parentheses) or specify it with an expression 
that generates a valid relocatable A-type address constant. 

The following RPL parameters and subparameters are required for GETIX: 

OPTCD = (CNV 
,DIR 

,{MJP|UPD|NSP) 
,(LOC|MVE}) 

GETIX can be issued either for update or not for update; 
OPTCD= NSP is interpreted as OPTCD = NUP. 

With OPTCD= MVE, AREALEN must be at least index control 
interval size. 

ARG = address 

The search argument for GETIX is the RBA of a control interval. 

To process the index of a key-sequenced data set with GETIX, you must open 
the cluster with: 

ACB MACRFKCNV, • • • ) 
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MNTACQ Macro (Mount Acquire) 

The format of the MNTACQ macro is: 



\labell MNTACQ RPL = address 



RPL = address 

specifies the address of the RPL that identifies your opened VSAM data set 
and your arguments. The following RPL parameters have meaning for 
MNTACQ: 

ACB = address 

identifies your VSAM data set. 

ARG- address 

identifies your arguments, address points to a parameter list, aligned 
on a fullword boundary as follows: 



Offset Length Contents 



Feedback area: address of an 
ECB WAIT list 



4 6 


VOLSER, target volume 


10 1 


Reserved 


11 1 


Argument entry count (N) 
(N = 1 to 255) 


12 4N 


Argument entries 


12+4(N-l) 


4 RBA for which an ACQUIRE is 
requested 



The maximum number of arguments is 255. 

For the specified list, MNTACQ will acquire (stage) the data cylinders 
corresponding to each RBA for the one given volume. The volume 
will be mounted if necessary. 

OPTCD = ({ADR|KEY} 
,{ASY|SYN) 
,{KEQ|KGE} 
,FKS) 

ADR is valid for entry-sequenced data set, error for key-sequenced 
data set or relative record data set. 
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KEY is valid for key-sequenced data set and relative record data set, 
error for entry-sequenced data set. 

If ASY is specified, you cannot WAIT on the RPLECB field for 
MNTACQ or ACQRANGE. You use the address placed in the 
parameter list feedback area. This address points to a list of ECBs (in 
standard WAIT list format) which you may use in place of the 
RPLECB field. 

GEN is not supported; if specified, it will give an error indication. 

All other OPTCD parameters are not applicable, and, if specified, are 
ignored with no error indication. 

Because your request may result in the staging of numerous cylinders, a single 
ECB is not sufficient for an asynchronous MNTACQ request. The RPLECB 
field is inoperative for the MNTACQ interface. Upon return from an 
asynchronous MNTACQ, the feedback area of the MNTACQ parameter list will 
contain the address of a standard ECB WAIT list. You must then use this list in 
conjunction with the WAIT macro or you may use the list in conjunction with 
the EVENTS macro of MVS. An asynchronous request must conclude with 
either CHECK, ENDREQ, or CLOSE. 

At the conclusion of this macro, the RPL is disconnected in a manner similar to 
that of a direct VSAM request. Any positioning in effect prior to execution of 
this macro will be lost. You may have to reposition. Chained RPLs are not 
supported by MNTACQ. 
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MODCB Macro (Modify an Access Method Control Block) 

The format of the MODCB macro used to modify an access method control 
block is: 



\label\ 


MODCB 


ACB = address 
[BSTRNO- number] 
[,BUFND = number] 
|,BUFNI- number] 
|,BUFSP = number] 
|,CATALOG = YES|NO| 
(,CRA = SCRA|UCRA| 
|,DDNAME - ddname] 
l¥X\£T= address] 
|,MACRF - (IADRH,CNV|I,KEYI 

|,CFX|NFX| 

[,DDN|DSN| 

|,DFR|NDFI 

|,DIR|I,SEQ||,SKPI 

|,ICI|NCI| 
I,IN||,OlT11 
|,NIS|SIS| 
|,NRM|AIX| 






kNRSlRSIl 






(,NSR|LSR|GSR| 

|,NUB|UBF|)| 
|,MAREA = address] 
|,MLEN- number] 
|,PASS\V1> = address] 
|,RMODE3! - f ALLIBUFFICBINONEJI 
|,SHRPOOL = number] 
|,STRNO = number] 



Note: The RMODE31 parameter replaces the AMODE31 subparameter shown 
in previous releases. 

The parameters of the MODCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that generate valid 
relocatable A-typc address constants, in register notation, as S-type address 
constants, and as indirect S-type address constants. Appendix C, "Operand 
Notation" on page 181, further defines these operand expressions. 

label 

is I to 8 characters that provide a symbolic address for the MODCB macro. 

ACB = address 

specifies the address of the access method control block to be modified. 
The data set identified by the access method control block must not be 
opened. A request to modify the access method control block of an open 
data set will fail. 
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Note: The remaining parameters represent parameters of the ACB macro that 
can be modified. The value specified replaces the value, if any, presently in the 
access method control block. There are no defaults. For an explanation of these 
parameters, see "ACB Macro (Generate an Access Method Control Block at 
Assembly Time)" on page 34. 

If MODCB is used to modify a MACRF subparameter, other subparameters are 
unaffected, except when they are mutually exclusive. For example, if you specify 
MACRF = ADR in the MODCB and MACRF = KEY is already indicated in the 
control block, both ADR and KEY will now be indicated. But, if you specify 
MACRF = UBF in the MODCB and NUB is indicated, only UBF will now be 
indicated. 

The RMODE31 parameter tells the VSAM OPEN routines where to obtain 
storage for the control blocks and I/O buffers. Therefore, the only time the 
values specified by the RMODE31 parameter have any effect on VSAM is on the 
setting just before an OPEN is issued. At other times, changing these values has 
no effect on the residency of the control blocks and I/O buffers. 

If MODCB RPL is used to change the address of an ACB, you must first issue 
an ENDREQ macro. 



Example: MODCB Macro (Modify an Access Method Control Block) 



In this example, a MODCB macro is used to modify the name of the exit list in 
an access method control block. 

MODCB ACB=BLOCK, BLOCK was generated at 

EXLST=EGRESS assembly. 
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MODCB Macro (Modify an Exit List) 



The format of the MODCB macro used to modify an exit list is: 



\label\ 


MODCB 


EXLST- address 
[,EODAD - {[address\l\\S\m)\ 
|,JRNAD - (\address\l\\S\\X\)\ 
|,LERAD » (\address\\,A\S\[X\)\ 
|,SYNAD - (\address\lA\X\[M)\ 



The subparamcters of the MODCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that generate valid 
relocatable A-type address constants, in register notation, as S-type address 
constants, and as indirect S-type address constants. Appendix C, "Operand 
Notation" on page 181, further defines these operand expressions. 

Note: See Data Facility Product: Customization for the factors that determine 
the addressing mode and the parameter list residency mode set when the exit 
routine gets control. 

label 

is 1 to 8 characters that provide a symbolic address for the MODCB macro. 

EXLST ~ address 

specifies the address of the exit list to be modified. You can modify an exit 
list at any time— that is, before or after opening the data set(s) for which the 
list indicates exit routines. Ycu cannot, however, add an entry to the exit 
list if it will change the exit list's length; the exit list must already be large 
enough to contain the new exit address. The order in which addresses are 
stored in the EXLST control block is: HODAD, SYNAD, LERAD, 
JRNAD, and UPAD. For example, if you generate an exit list with only 
the LERAD exit, you can add entries for EODAD and SYNAD later, you 
cannot add the JRNAD exit address, because doing so would increase the 
size of the EXLST control block. The MODCB macro does not support 
the UPAD user exit. 

Note: If the JRNAD exit is changed for an OPEN ACB, then the ACB 
must be closed and reopened in order to use the modified JRNAD exit. 

For more information about user exit routines sec Data Facility Product: 
Customization. 

The remaining parameters represent parameters of the EXLST macro that can be 
modified or added to an exit list. For an explanation of these parameters, see 
"EXLST Macro (Generate an Exit List at Assembly Time)" on page 66. 
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MODCB-EXLST 

Example: MODCB Macro (Modify an Exit List) 

In this example, a MODCB macro is used to activate an exit in an exit list. 

MODCB EXLST=(*. Indirect notation is used 
EXLSTADR), to specify the address of 
EODAD=(EOD,L,A) the exit list, which was 
generated at execution. 



EOD DC 
EXLSTADR DS 



C' ENDUP 1 
F 



When the exit list was 
generated, its address was 
saved here. 



The MODCB macro's parameters arc: 



• EXLST specifics that the address of the exit list to be modified is located at 
EXLSTADR. 

• EODAD specifics that the entry for the end-of-data routine is to be mariced 
active in the exit list whose address resides at EXLSTADR. The name of the 
end-of-data routine, ENDUP, is located at EOD. 
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MODCB Macro (Modify a Request Parameter List) 

The format of a MODCB macro used to modify a request parameter list is: 



[label] 


MODCB 


RPL= address 
j,ACB = address] 
|, AREA = address] 
{, AREALEN = number] 
|,ARG - address] 
|,ECB = address] 
|,KEYLEN- number] 
(,MSGAREA = address] 
|,MSGLEN = number] 
|,NXTRPL = address] 
|,OPTCD - (fADR|CNV|KEY| 

(,DIR|SEQ|SKP| 

|,ARD|LRD| 

|,FWD|BVVD| 

|,ASY|SYNI 

|,NSP|NUP|LPDf 

[,KEQ|KGEI 

|,FKS|GEN| 

|,LOC(MVEl)I 






f,RECtEN = number] 
|,TRANSID- number] 



The parameters of the MODCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that generate valid 
relocatable A-type address constants, in register notation, as S-type address 
constants, and as indirect S-type address constants. Appendix C, "Operand 
Notation" on page 181, further defines these operand expressions. 

label 

is 1 to 8 characters that provide a symbolic address for the MODCB macro. 

RPL = address 

specifics the address of the request parameter list to be modified. You may 
not modify an active request parameter list; that is, one that defines a 
request that has been issued but not completed. To modify such a request 
parameter list, you must first issue a CHECK or an ENDREQ macro. 

Note: The remaining parameters represent parameters of the RPL macro that 
can be modified. The value specified replaces the value, if any, presently in the 
request parameter list. There are no defaults. For an explanation of these 
parameters, see "GENCB Macro (Generate a Request Parameter List at 
Execution Time)" on page 80. 

If MODCB is used to modify an OPTCD subparameter within a group of 
subparameters, the current subparameter for that group is changed, because only 
one subparameter in a group is effective at a time. Only the OPTCD 
subparameter specified is changed; all other OPTCD subparameters remain 
unchanged. 
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Example: MODCB Macro (Modify a Request Parameter List) 



In this example, a MODCB macro is used to modify the record length field in a 
request parameter list. 

Note: This example also shows the one exception to GENCB, MODCB, 
SHOWCB, and TESTCB building a parameter list and passing it to the control 
block manipulation module in register 1. In this example, the RPL address (in 
register 2) would be loaded into register 1 and the RECLEN value (in register 3) 
would be loaded into register 0. These registers would be passed to the control 
block manipulation macro. This will occur if the LIST, EXECUTE, or 
GENERATE form of the MODCB macro is not used and the only parameter 
specified, besides RPL, is RECLEN. 

L 3, length Load the new record length. 

MODCB RPI/=(2), Register 2 contains the address 

of the request parameter list. 

RECLEN=(3) Register 3 contains the record 
length. 



The MODCB macro's parameters are: 

• RPL specifies that register 2 contains the address of the request parameter list 
to be modified. 

• RECLEN specifies that the record length field is to be modified. The 
contents of register 3 will replace any current value in the RECLEN field. 
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MRKBFR Macro (Mark Buffer) 

The format of the MRKBFR macro is: 



MRKBFR 



MARK - {DINVALlD|XINVALID|OUT|RLS} 
,RPL = address 



MARK= {DINVALID|XINVALID|OUT|RLS} 

specifies whether to mark for output or to release from exclusive control or 
shared status the buffer identified in the RPL. To do both, issue 
MRKBFR twice, once with MARK = OUT, again with MARK = RLS. 

DINVALIDIXINVALID 

specifies whether to mark the data component or index component 
buffers invalid. The buffers to be invalidated are identified as those 
which contain records, whose RBA values are within the RBA range 
pointed to by the RPL ARG address. DINVALID specifies that the 
data component buffers are to be marked invalid; XIN VALID 
specifies that the index component buffers are to be marked invalid. 

OUT 

indicates that the buffer is to be marked for output. The buffer is 
kept under exclusive control or in shared status. 

RLS 

indicates that the buffer is to be released from exclusive control or 
shared status. 

RPL = address 

specifies the address of the request parameter list that defines the 
MRKBFR request. Use the RPL used by SCIIBFR or GET to locate the 
buffer being marked or released. These RPL parameters have meaning for 
MRKBFR: 

ACB = address 



ARG = address 

The address of the 8-byte field that contains the beginning and ending 
RBAs of the range to be searched on. 

ECB = address 



TRANSID -'number 

All other RPL parameters are ignored. RPLs are assumed not to be 
chained. OPTCD=LOC is assumed. 

If the ACB to which the RPL is related has MACRF = GSR, the 
program that issues MRKBFR must be in supervisor state with 
protection key to 7. 
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OPEN Macro (Connect Program and Data) 

The format of the OPEN macro is: 



\Iabel\ 


OPEN 


(address \(options)\,...) 
I,MODE = {24|31}| 



label 

is 1 to 8 characters that provide a symbolic address for the OPEN macro. 

address 

specifics the address of the ACB or DCB for the data sct(s) to be opened. 
You may specify the address in register notation (using a register from 2 
through 12, in parentheses) or specify it with an expression that generates a 
valid relocatable A-type address constant. If you use register notation to 
open only one data set, you must enclose the expression identifying the 
register in two sets of parentheses: for example, OPEN ((2)). 

options 

arc options parameters for use only in opening non-VSAM data sets. If 
any options are specified with the address of an access method control 
block, VSAM ignores them. 

MODE - 

specifies the format of the OPEN parameter list that is to be generated. 



24 



specifics that a standard form (24-bit) parameter list address is to be 
generated. The parameter list must reside below 16 megabytes and 
point to an ACB residing below 16 megabytes. This is the default 
parameter. 



31 



specifies that a long form (31 -bit) parameter list address is to be 
generated. This parameter value must be coded if the parameter list 
or the VSAM/VTAM ACB resides above 16 megabytes. 

Note: If the VSAM control blocks and buffers are to reside above 16 megabytes, 
the RMODE31 parameter must be specified in the ACB before the OPEN is 
issued. 

Because the OPEN parameters are positional, include a comma for options (even 
if you don't specify options) before a subsequent parameter. 
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Example 1: OPEN Macro used to open two data sets. 



In this example, the access method control block for one data set was generated 
at execution; the other was generated at assembly. 

An access method control block. 



GENCB 


BLK=ACB, 
DDNAME=DATA 


LTR 


15,15 


BNZ 


ERROR 


LR 


2,1 


OPEN 


(BLOCK,, (2)) 



BLOCK ACB 



Address of the control block. 

A label is used for the access 
method control block generated 
by ACB; register notation is used 
for the one generated by GENCB. 
The two commas indicate the 
omission of options. 

Another access method control 
block. 



Example 2: OPEN Macro with a parameter list above 16 megabytes. 



This example shows a program being opened with a parameter list that may 
reside above 16 megabytes. 



OPLSTA OPEN 



M0DE=31, 
MF=(E,OPLSTB) 



OPLSTB OPEN (ACB1,,ACB2), 
M0DE=31, 
MF=L 

Since MODE = 31 is coded in the list form of the OPEN macro, VSAM ACBs 
and the OPEN parameter list may reside above 16 megabytes. 

Note: Consistency must be maintained while using the MODE operand in the 
MF= L and MF = E versions of the OPEN macro. If MODE = 3 1 is specified in 
the MF = L version, then MODE — 31 must also be coded in the corresponding 
MF= E version of the macro. Unpredictable results may occur if this rule is not 
followed. 

MF = E and MF = L arc not required. OPEN (ACB1), MODE = 31 is also valid. 
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POINT Macro (Position for Access) 

The format of the POINT macro is: 



[Iabel\ 


POINT 


RPL = address 



label 

is 1 to 8 characters that provide a symbolic address for the POINT macro. 

RPL- address 

specifies the address of the request parameter list that defines the request. 
You may specify the address in register notation (using a register from 1 
through 12, enclosed in parentheses) or specify it with an expression that 
generates a valid relocatable A-type address constant. 



Example: Position with POINT 



In this example, the POINT macro is used to position at a record identified by a 
full key (5-bytc) search argument, compared equal. 
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POINT 



BLOCK ACB 
POSITION RPL 



DDNAME=IO 



Default MACRF subparameters 
sufficient. 



ACB=BLOCK, 

AREA=W0RK, 

AREALEN=50, 

ARG=SRCHKEY, 

OPTCD=(KEY,SEQ,SYN,KEQ,FKS) 



ARG parameter and KEQ and 
FKS OPTCD subparameters 
define the POINT request. 



LOOP 



MVC SRCHKEY, source 
POINT RPL=POSITION 



Search argument for 
positioning, moved in from 
a table or a transaction 
record. 



L00P1 



LTR 


15,15 


BNZ 


ERROR 


GET 


RPIr=POSITION 


LTR 


15,15 


BNZ 


ERROR 



Process the record. Decide whether to skip to another 
position (forward or backward). 

Yes; skip. 

No; continue in 
consecutive sequence. 

Request was not accepted, 
or failed. 

Search argument for 
positioning. 

VSAM puts a record here 
for each GET request. 



BE 


LOOP 


B 


L00P1 


ERROR 




SRCHKEY DS 


CL5 


WORK DS 


CL50 
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PUT Macro (Store a Record) 



The format of the PUT macro is: 



[labeli 


PUT 


RPL = address 



label 

is 1 to 8 characters that provide a symbolic address for the PUT macro. 

RPL = address 

specifics the address of the request parameter list that defines the request. 
You may specify the address in register notation (using a register from 1 
through 12, enclosed in parentheses) or specify it with an expression that 
generates a valid relocatable A-type address constant. 

Note: If the PUT macro is being used to load records into an empty data set, 
the STRNO value in the access method control block must be 1, and RPL 
OPTCD = DIR must not be specified. However, for an empty relative record 
data set, DIR is allowed. 



Example 1: Kcycd-Scqucntial Insertion 



In this example, a PUT macro is used to perform keyed-sequential insertion. 
Variable-length records with a key length of 15 bytes are to be moved from a 
work area. Some records will be inserted between existing records; other records 
will be added at the end of the data set. 



BLOCK 
LIST 



ACS DDNAWE=OUTPUT, 

MACRF=(KEY,SEQ,OUT) 



LOOP 



RPL 


ACB=BLOCK, 

AREA=BUILDRCD, 

AREALEN=250, 

OPTDC=(KEY,SEQ, 

SYN,NUP,MVE) 




L 


2, source 


Put length of record to 
be inserted into 
register. 


MODCB 


RPL=LIST, 
RECLEN=(2) 


Indicate record length 
in request parameter 
list. 


LTR 


15,15 




BNZ 


CHECKO 




PUT 


RPL=LIST 




LTR 


15,15 




BNZ 


ERROR 




B 


LOOP 





CHECKO 



Modification failed. 
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PUT 



ERROR 



BUILDRCD DS 



CL250 



Request was not accepted, 
or failed. 

Work area for building 
records . 



The request parameter list, LIST, is associated with the access method control 
block, BLOCK. The length of each record to be inserted is put into register 2, 
which is subsequently used by MODCB to change the record length in the 
request parameter list. The record length is, therefore, correctly indicated in the 
request parameter list before the PUT macro is issued. The execution of the 
PUT macro causes VSAM to skip ahead (never back) to the next record. 



Example 2: Recording RBAs When Loading 



In this example, a PUT macro is used to record the RBAs of records as they are 
loaded into a key-sequenced data set. The RBAs are recorded in a table with 
20-byte entries (4 bytes for RBA, 15 bytes for associated key, and 1 byte of 
padding so the next entry begins on a fullword boundary). 



LOOP 



LA 


3,RBATABLE 


Address of the beginning of 
the table. 


i 


2, source 


Put length of record to be 
inserted into register 2. 


MODCB 


RPL=LIST, 
REGLEN=(2> 


Indicate record length in 
request parameter lisrt. 


LTR 


15,15 




BNZ 


CHECKO 




PUT 


RPL=LIST 




LTR 


15,15 




BNZ 


ERROR 




SHOWCB 


AREA=(3), 
FIELDS=RBA, 
LENGTH=4, 
RPL=LIST 


Each SHOWCB puts a record's 
RBA into the table. 


LTR 


15,15 




BNZ 


CHECKO 




MVC 


4(15,3), 
key fie Id 


Put the record's key field 
in the table. 


LA 


3,20(3) 


Point to the next entry. 


B 


LOOP 





ERROR 



Request was not accepted, 
or failed. 



112 MVS/XA VSAM Administration: Macro Instruction Reference 



PUT 



CHECKO 



Modification or display 
failed. 



DSECT 



Get enough virtual storage 
for as many table entries 
as there are records in 
the data set. 



RBATABLE DS 


OF 


RBA DS 


CL4 


KEY DS 


CL15 


DS 


CL1 



Padding to keep each RBA 
entry on a fullword 
boundary: SHOWCB's display 
area must be on a fullword 
boundary. 

The need to process a key-sequenced data set by address should be unusual, but 
by recording the RBA of each record in a key-sequenced data set, you have 
search arguments for possible processing of the data set by addrcssed-direct 
retrieval and by addrcsscd-scqucntial retrieval using the POINT macro. (You 
don't need to know RBAs to process a key-sequenced data set by simple 
addressed -sequential retrieval, since you go from the beginning without any 
skips.) 

You can display the RBA of a record after you issue a GET or a POINT, as well 
as after you issue a PUT. 

Example 3: Loading a Relative Record Data Set (Skip-Sequential and Dirccl Processing) 

In this example, a PUT macro is used to store twenty 100-byte records in slots 5, 
10, 15,..., 100 of the data set. MODCB is used to switch to direct processing, and 
a PUT is used to store records in slots 26 and 51 of the data set. 



OUTACB ACB 


MACRF=(SKP,OUT, 
DIR,KEY) 


GENCB 


BLK=RPL, 

ACB=OUTACB, 

AREA=W0RK, 

AREALEN=100, 

ARG=RCDN0, 

OPTCD=(KEY,SKP) 


LTR 


15,15 


BNZ 


GENFAIL 


LR 


5,0 


LR 


6,1 


LA 


7,5 


ST 


7,RCDN0 


LA 


10,20 



Generate a request 
parameter list at 
execution time. 



Save length of RPL. 

Save address of RPL. 

Initialize increment 
value. 

Initialize argument to 
slot 5. 

Initialize loop counter. 
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PUT 



LOOP 



PUT 


RPL=(6) 


LTR 


15,15 


BNZ 


PUTERR 


L 


l,RCDNO 


AR 


1,7 


ST 


l.RCDNO 


BCT 


10, LOOP 


MODCB 


RPL=(6), 
OPTCD=(DIR,KEY) 


LTR 


15,15 


BNZ 


GENFAIL 


LA 


7,51 


ST 


7,RCDNO 



B 
GENFAIL . . . 

PUTERR 

RETURN 
WORK DS 

RCDNO DS 



Move new record into work. 
Store record. 



Request was not accepted, 
or failed. 



Increment argument by 5. 



Switch to direct processing 
to store records in slots 
51 and 26. 



RETURN 



CL100 



CL4 



Initialize argument to slot 
51. 

Move new record into WORK. 



PUT 


RPL=(6) 


Store record in slot 51. 


LTR 


15,15 




BNZ 
LA 


PUTERR 
7,26 


Request was not accepted, 
or failed. 


ST 


7,RCDNC 


Initialize argument to slot 
26. 






Move new record into WORK. 


PUT 


RPL=(6) 


Store record in slot 26. 


LTR 


15,15 




BNZ 


PUTERR 


Request was not accepted, 



or failed. 



Generation or modification 
failed. 

PUT request was not 
accepted, or failed. 

Terminate program. 

100 -byte work area that 
contains record to be 
stored by PUT macro. 

4-byte relative record 
number. 
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PUT 



Both skip-sequential and direct processing can be used to create a relative record 
data set. The ACB is opened for output. The 4-byte search argument 
(RCDNO) indicates the slot number where the record is to be stored. 



Example 4: Kcycd-Scqucntia] Insertion (Relative Record Data Set) 



In this example, a PUT macro is used to insert twenty 100-byte records into 
empty slots of a previously loaded relative record data set. If the slot is empty 
when the PUT is issued, the record is stored and the slot number (returned in the 
argument field) is stored in a table. If the slot is not empty when the PUT is 
issued, a duplicate record error indication is returned. When a duplicate record is 
indicated, the PUT is reissued until the record is successfully stored in an empty 
slot in the data set. 



OUTACB ACB 


MACRF=(KEY,SEQ, 
OUT) 


GENCB 


BLK=RPL, 

ACB=OUTACB, 

AREA=WORK, 

AREALEN=100, 

ARG=RCDNO, 

OPTDC=(KEY,SEQ) 


LTR 


15,15 


BNZ 


GENERR 


LR 


6,1 


LA 


4,RRNTABLE+80 


LA 


3,RRNTABLE 


WRITERCD ... 




PUT 


RPL=(6) 


LTR 


15,15 


BZ 


STRCDNO 


LA 


10,8 


CLR 


10,15 


BNE 


PUTERR 



Generate a request parameter 
list. 



Save the address of the RPL. 

Initialize address of end of 
table. 

Initialize index to relative 
record number table. 

Move record into work area. 



Branch, if PUT is successful 
Test for logical error. 



TESTCB RPL=(6),FDBK=8, Test for duplicate record. 
ERET=TESTERR 



BE WRITERCD 
B PUTERR 



Branch, if duplicate record, 
and try to store record in 
next slot. 
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STRDCNO 




• • • 




MVC. 


0(4,3)RCDNO 




LA 


3,4(3) 




CLR 


3,4 




BE 


RETURN 




B 


WRITERCD 


GENERR 


... 




TESTERR 


... 




PUTERR 






RETURN 


• • 




RCDNO 


DS 


CIA 


RRNTABLE 


DS 


20F 


WORK 


DS 


CL100 



Store relative record 
number in RRNTABLE. 

Increment to next table 
entry. 



If table full, return to 
caller. 

Write next record. 

Error routine for GENCB 
macro. 

Error routine for TESTCB 
macro. 

Error routine for PUT 
macro. 

Return to caller or 
terminate program. 

4-byte relative record 
number (argument) field. 

Relative record number 
table. 

100 -byte work area that 
contains record to be 
stored by PUT macro. 



Each record is stored in the next available slot in the data set. When a record is 
successfully stored, its relative record number is recorded in a table. 



Example 5: Skip-Sequential Insertion 



In this example, one PUT macro is used to insert multiple fixed-length, 100-byte 
records. Records are to be moved asynchronously from a work area. 



OUTPUT ACB MACRF=(KEY,SKP, 
OUT) 



GENCB BLK=RPL, 
C0PIES=5, 
ACB=0UTPUT, 
AREALEN=100, 
0PTCD=(KEY,SKP, 
ASY,NUP,MVE), 
RECLEN=100 

LTR 15,15 

BNZ CHECKO 



Generate 5 request 
parameter lists at 
execution. 
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Calculate length of each list and use register notation with 
the MODCB macro to complete each list. 



MODCB 



RPL=(2), 

AREA=(3), 

NXTRPL=(4) 



LTR 15,15 

BNZ CHECKO 

Increase the value in each register and repeat the MODCB 
until all five request parameter lists have been completed, 
The last time, register 4 must be set to 0. 



LOOP 



PUT RPL=(2) 

LTR 15,15 
BNZ NOTACCEP 



Restore address of first 
list in register 2. 
Build 5 records in WORK. 

Register 2 points to the 
first request parameter 
list in the chain. The 
five records in WORK are 
stored with this one 
PUT request. 



CHECK RPL=(2) 

LTR 15,15 

BNZ ERRO 

B LOOP 



CHECKO 

NOTACCEP 

ERROR 

WORK 



DS 



CL500 



Generation or modification 
failed. 



Display the feedback field 
in each request parameter 
list to find out which one 
had an error. 

Contains five 100 -byte work 
areas . 



You give no search argument for storage: VSAM knows the position of the key 
field in each record and extracts the key from it. Skip-sequential insertion differs 
from keyed-direct insertion in the sequence in which records may be inserted 
(ascending nonconsccutive sequence versus random sequence) and in 
performance. 

With skip-sequential insertion, if you insert two or more records into a control 
interval, VSAM doesn't write the contents of the buffer to direct-access storage 
until you have inserted all the records. With direct insertion, VSAM writes the 
contents of the buffer after you have inserted each record. 
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Example 6: Keyed-Direct Insertion 



In this example, a PUT macro is used to move fixed-length, 100-byte records 
from a work area. 



OUTPUT ACB 



DIRECT RPL 



MACRF=(KEY,DIR, 
OUT) 

ACB=OUTPUT, 

AREA=WORK, 

AREALEN=100, 

OPTCD=(KEY,DIR, 

ASY,NUP,MVE), 

RECLEN=100 



LOOP 



PUT 


RPIr=DIRECT 


LTR 


15,15 


BNZ 


NOTACCEP 



CHECK RPL=DIRECT 

LTR 15,15 

BUZ ERROR 

B LOOP 

NOTACCEP ... 

ERROR 



Request was not accepted. 
Request failed. 



WORK DS CL100 

The macros are as follows: 



Work area. 



• ACB specifies that the data set, OUTPUT, into which records are to be 
inserted, is opened for keyed-direct, output processing. 

• RPL specifies that the record to be inserted into the OUTPUT data set 
resides in a 100-bytc area, WORK. 

VSAM extracts the key from the key field of each record found at WORK. 
Using keyed-direct access is similar to using skip-sequential access. 
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Example 7: Addrcsscd-Scqucntial Addition 



In this example, a PUT macro is used to add variable-length records to a data 
set. The data set is assumed to be an entry-sequenced data set, because records 
cannot be inserted into or added to a key-sequenced data set with addressed 
access. 



BLOCK ACB 
LIST RPL 



MACRF=(ADR,SEQ, 
OUT) 

ACB=BLOCK, 

AREA=NEWRCD, 

AREALEN=100, 

OPTCD=(ADR,SEQ, 

SYN,MVE) 



LOOP 





L 


3, source 




MODCB 


RPL=LIST, 
RECLEN=(3) 




LTR 


15,15 




BNZ 


CHECKO 




PUT 


RPL=LIST 




LTR 


15,15 




BNZ 


ERROR 




B 


LOOP 


CHECKO 






ERROR 







Build the record. 

Put the length of the 
record into register 3. 

Indicate length of new 
record. 



Modification failed. 

Request was not accepted, 
or failed. 



NEWRCD DS 



CL100 



Build record in this work 
area. 



Each record is stored in the next position after the last record in the data set. 
You do not have to specify an RBA or do any explicit positioning (with the 
POINT macro). Addressed addition of records is always identical to loading a 
data set: When additional space is required, VSAM extends the data set. 

The only difference between addressed -sequential and addresscd-direct addition is 
when the buffers are written to external storage. The buffer is written to external 
storage only when it is full for sequential addition; it is written after each record 
for direct addition. You cannot use direct storage to load records into a data set 
for the first time; you must use sequential storage. 
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Example 8: Kcyed-Scqucntial Update 



In this example, GET and PUT macros are used to retrieve and update 
fixed-length, 50-byte records. Records are updated synchronously in a work area. 
This example requires the use of a work area because you cannot update a record 
in the I/O buffer. 



UPDATA ACB 
LIST RPL 



MACRF=(KEY,SEQ, 
OUT) 

ACB=UPDATA, 

AREA=WORK, 

AREALEN=50, 

OPTCD=(KEY,SEQ, 

SYN,UPD,MVE) 



UPD indicates the record may 
be stored back (or deleted). 



LOOP GET RPL=LIST 
LTR 15,15 
BNZ ERROR 

Decide whether to update the record. 



BE 



LOOP 



Do update the record. 



Do not update it; retrieve 
another. 



ERROR 



PUT 


RPL=LIST 


Store the record back. 


LTR 


15,15 




BNZ 


ERROR 




B 


LOOP 








Request was not accepted, or 
failed. 



WORK 



DS 



CL50 



VSAM puts the retrieved record 
here. 



A GET for update (OPTCD= UPD) must precede a PUT for update. Besides 
retrieving the record to be updated, GET positions VSAM at the record retrieved, 
in anticipation of the succeeding update (or deletion). It is not necessary for you 
to store back (or delete) the record that you retrieved for update. VSAM's 
position at the record previously retrieved allows you to issue another GET to 
retrieve the following record. You cannot then, however, store back the previous 
record: The position for update has been forgotten because of the following GET. 
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Example 9: Keyed-Direct Update 



In this example, GET and PUT macros are used to retrieve and update records. 
The MODCB macro is used to modify record length (RECLEN) in the request 
parameter list when an update causes the record length to change. The 
maximum record length is 120 bytes. The search argument is a full key (5 bytes), 
compared equal. 



INPUT ACB MACRF=(KEY,DIR, 
OUT) 

UPDTE RPL ACB=INPUT, 
AREA=IN, 
AREALEN=120, 
OPTDC=(KEY,DIR, 
SYN,UPD,KEQ, 
FKS,MVE), 
AR6=KEYAREA, 
KEYLEN=5 



UPDTE indicates the record 
may be stored back 
(or deleted). 



Process input and get search argument into KEYAREA; proceed 
to retrieve a record. 



LOOP GET 


RPL=UPDTE 


LTR 


15,15 


BNZ 


ERROR 


SHOWCB 


RPL=UPDTE, 
AREA=RLNGTH, 
FIELDS=RECLEN, 
LENGTH=4 


LTR 


15,15 


BNZ 


CHECKO 


Update the record. Does the u 
length? 


BE 


STORE 


L 


5 , length 


MODCB 


RPL=UPDTE, 
RECLEN=(5) 


LTR 


15,15 


BNZ 


CHECKO 


STORE PUT 


RPL=UPDTE 


LTR 


15,15 


BNZ 


ERROR 


B 


LOOP 



Display the length of the 
record. 



No; length not changed. 

Yes; load new length into 
register 5. 

Modify length indication 
in the request parameter 
list. 
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ERROR 
CHECKO 



Request was not accepted, or 
failed. 

Display or modification 
failed. 



IN 



DS 



KEYAREA DS 



RLNGTH DS 



CL120 



CL5 



Work area for retrieving, 
updating, and storing a 
record. 

Search argument for 
retrieving a record. 

Area for displaying the 
length of a retrieved record. 



You cannot update records in the I/O buffer. A direct GET for update positions 
VSAM at the record retrieved, in anticipation of storing back (or deleting) the 
record. This positioning also allows you to switch to sequential access to retrieve 
the next record. When PUT is issued after a DIRUPD GET request, PUT 
causes VSAM to release exclusive control. 

You do not have to store back a record that you retrieve for update, but, if you 
do not store it back before another retrieval, the current updates are lost. 
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Example 10: Addrcsscd-Scqucntial Update 



In this example, GET and PUT macros are used to retrieve and update records in 
an entry-sequcnced data set. The records arc variable in length, a maximum of 
200 bytes. The lengths of the records are not changed by update (the length of a 
record can never be changed by addressed access). 



ENTRY ACB 
ADRUPD RPL 



MACRF=(ADR,SEQ,OUT) 

ACB=ENTRY, 

AREA=W0RK, 

AREALEN=200, 

OPTCD=(ADR,SEQ, 

SYN,UPD,MVE) 



UPDTE indicates update (or 
deletion). 



LOOP 



GET RPL=ADRUPD 
LTR 15,15 
BNZ ERROR 



SHOWCB 


RPL=ADRUPD, 
AREA=RECLEN, 
FIELDS=RECLEN, 
LENGTH=4 


LTR 


15,15 


BNZ 


CHECKO 


PUT 


RPL=ADRUPD 


LTR 


15,13 


BNZ 


ERROR 


B 


LOOP 



ERROR 



CHECKO 



Find out how long the record 
is. 



Request was not accepted, or 
failed. 

Display failed. 



WORK DS 
RLNGTH DS 



CL200 
F 



Record-processing work area, 

Display area for length of 
records . 



If you have inactive records in your cntry-scquenccd data set, you may reuse the 
space they occupy by retrieving the records for update and restoring a new record 
in their place. 

With a key-scquenccd data set, it is not possible to change the length of records 
by addressed update because the index is not used and VSAM could not split a 
control interval if required because of changing record length. 

Addrcssed-direct update varies from sequential update in the specification of an 
RBA for a search argument. 
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Example 1 1: Marking Records Inactive 



In this example, GET and PUT macros are used to retrieve a record from an 
entry-sequenced data set and to mark it as inactive. (The record is marked as 
inactive by putting a hexadecimal 'FF' in the first byte of a record.) The inactive 
record will not be sequentially retrieved except for update. 



ENTRYSEQ ACB 



LIST 



RPL 



MACRF=(ADR,DIR, 
OUT) 

ACB=ENTRYSEQ, 

AREA=RECORD, 

AREALEN=100, 

OPTCD=(ADR,DIR, 

SYN,UPD,MVE), 

ARG=RBAAREA 



UPD indicates update; 
storing the record back 
marked inactive. 



LOOP GET RPL=LIST 
LTR 15,15 
BNZ ERROR 

Decide whether you still want the data in the record. 



BE 



LOOP 



MVI RECORD .X'FF' 

PUT RPL=LIST 

LTR 15,15 

BNZ ERROR 

B LOOP 



Yes; retrieve the next 
record. 

No; flag the record 
inact ive . 

Storing the record with 
an inactive indicator is 
equivalent to deletion 
for an entry-sequenced 
data set. 



ERROR 



RECORD DS 



RBAAREA DS 



CL100 



Request was not accepted, 
or failed. 

Work area for marking 
records. 

Search argument for 
retrieving the record. 



Records of an entry-sequenced data set can't be deleted. If a record loses its 
usefulness for your application, your program can mark it inactive by placing a 
unique flag in some conventional part of the record so that when your programs 
retrieve the record thereafter they can recognize and bypass it. You can use the 
space occupied by an inactive record by retrieving it for update and storing a new 
record in its place. 



1 24 M VS/XA VSAM Administration: Macro Instruction Reference 



PUTIX 
PUTIX Macro (Store an Index Record) 

The format of the PUTIX macro is: 



\label\ PUTIX RPL = address 



where: 

label 

is 1 to 8 characters that provide a symbolic address for the PUTIX macro. 

RPL = address 

specifics the address of the request parameter list that defines this PUTIX 
request. You may specify the address in register notation (using a register 
from 1 through 12, enclosed in parentheses) or specify it with an expression 
that generates a valid relocatable A-typc address constant. 

The following RPL parameters and subparameters are required for PUTIX: 

OPTCD = (CNV 
,DIR 
,UPD 
,MVE) 

OPTCD = LOC is not allowed. 

AREALEN 

must be at least index control interval size. 

The contents of a control interval must previously have been retrieved for update 
by wayofGETIX. 

To process the index of a key-sequenced data set with GETIX, you must open 
the cluster with: 

ACB MACRF=(CNV,...) 
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RPL Macro (Generate a Request Parameter List at Assembly Time) 



The format of the RPL macro is: 



]Iabei] 


RPL 


(ACB - address] 
UM-VSAMI 
I,AREA = address] 
|,AREALEN - number] 
|,ARG = address] 
\,V.CB = address] 
(,KEYLEN -raimM 
j,MSGAREA - address] 
|,MSGLEN =* number] 
|,NXTRPL = address] 
(,OPTCD = ([ADR|CNV|KEY] 

l,DIR|SE2|SKP| 

(,ARI)|LRD| 

|,FYVD|BYVD| 

|,ASY|SYNJ 

|,nsp|nlp|lpd| 
(,ke2ik<;e| 

(,FKS|GEN| 

|,NWAITX|\VAITX| 

IXOCI.MVEDI 


- 




kRECLEN^ number^ 
ITRASSID=> number] 



Values for RPL macro parameters can be specified as absolute numeric 
expressions, character strings, codes, and expressions that generate valid 
relocatable A-type address constants. 

label 

is 1 to 8 characters that provide a symbolic address for the request 
parameter list that is generated. You can use it in the request macros to 
give the address of the list. You can use it in the NXTRPL parameter of 
the RPL macro, when you are chaining request parameter lists, to indicate 
the next list. 

ACB = address 

specifies the address of the access method control block that identifies the 
data set to which access will be requested. If you used the ACB macro to 
generate the control block, you may specify the label of that macro for the 
address. If the ACB parameter is not coded, you must specify the address 
before issuing the request. 

AM = VSAM 

specifics that the access method using the control block is VSAM. 

AREA = address 

specifies the address of a work area to and from which VSAM moves a data 

record if you request it to do so (with the RPL parameter 

OPTCD = MVE). If your request is to process records in the I/O buffer 
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(OPTCD = LOC), VSAM puts into this work area the address of a data 
record within the I/O buffer. 

AREALEN «= number 

specifies the length, in bytes, of the work area whose address is specified by 
the AREA parameter. Its minimum for OPTCD = MVE is the size of a 
data record (of the largest data record, for a data set with records of variable 
length). For OPTCD = LOC, the area should be 4 bytes to contain the 
address of a data record within the I/O buffer. 

ARG ■ address 

specifies the address of a field that contains the search argument for direct 
retrieval, skip-sequential retrieval, and positioning. For a relative record 
data set, the ARG field must be 4 bytes long. For direct or skip-sequential 
processing, this field contains your search argument, a relative record 
number. For sequential processing (OPTCD = (KEY.SFQ)), the 4 bytes 
arc required for VSAM to return the feedback RRN. For keyed access 
(OPTCD = KEY), the search argument is a full or generic key or relative 
record number; for addressed access (OPTCD = ADR), it is an RBA. If 
you specify a generic key (OPTCD = GEN), you must also specify in the 
KEYLEN parameter how many of the bytes of the full key you are using 
for the generic key. ARG is also used with WRTBFR and MRKB1 R. Its 
usage with these macros is described in "Sharing Resources" in VSAM 
Administration Guide. 

ECB = address 

specifics the address of an event control block (ECB) that you may supply. 
VSAM indicates in the ECB whether a request is complete or not (using 
standard completion codes, which arc .described in Data Areas). You can 
use the ECB to determine that an asynchronous request is complete before 
issuing a CHECK macro. (If you issue a CHECK before a request is 
complete, you give up control and must wait for completion.) The ECB 
parameter is always optional. 

KEYLEN = number 

specifies the length, in bytes, of the generic key (OPTCD = GEN) you are 
using for a search argument (given in the field addressed by the ARG 
parameter). This parameter is specified as a number from 1 through 255; it 
is required when the search argument is a generic key. For full-key 
searches, VSAM knows the key length, which is taken from the catalog 
definition of the data set when you open the data set. 

MSGARKA- address 

specifics the address of an area that you may, optionally, supply for VSAM 
to send you a message in case of a physical error. The format of a physical 
error message is given in "Reason Code (Physical Errors)" on page 26. 

MSGLEN = number 

specifies the size, in bytes, of the message area indicated in the MSGAREA 
parameter. If MSGAREA is specified, MSGLEN is required. The 
ininimum size of a message is 128 bytes; if you provide less than 128 bytes, 
no message is returned to your program. 
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NXTRPL = address 

specifies the address of the next request parameter list in a chain. Oinii this 
parameter from the macro that generates the last list in the chain. When 
you issue a request that is defined by a chain of request parameter lists, 
indicate in the request macro the address of the first parameter list in the 
chain. 

OPTCD = (|ADR|CNV|KEYJ 
I.D1R1SEQ1SKP1 
URD ILRDI 
|, FWD |BWD1 
I.ASY1 SVNI 
|,NSP|NUP|UPD| 
I. KEO IKGE1 
|,FKS|GEN| 
I. NWA1TX IWA1TXI 
|,LOC|MVEI) 

specifies the subparamcters that govern the request defined by the request 
parameter list. Each group of subparamcters has a default; subparamcters 
are shown in Figure 13 with defaults underlined. Only one subparameter 
from each group can be specified. Some requests do not require an 
subparameter from all of the groups to be specified. The groups that aren't 
required arc ignored; thus, you can use the same request parameter list for a 
combination of requests (GET, PUT, POINT, for example) without 
zeroing out the inapplicable subparamcters each time you go from one 
request to another. 

Option Meaning 

ADR Addressed access to a key-scquenced or an entry-sequenced 

data set: RBAs are used as search arguments and sequential 
access is done by entry sequence. 

CNV Control interval access (this type of access is described in 

VSAM Administration Guide). 

KEY Keyed access to a key-sequenced or relative record data set: 

keys or relative record numbers are used as search arguments 
and sequential access is done by key or relative record number 
sequence. 

DIR Direct access to a key-scqucnccd, entry-sequenccd, or relative 

record data set. 

SEQ Sequential access to a kcy-scqucnccd, entry-scqucnccd, or 

relative record data set. 

SKP Skip sequential access to a key-scqucnccd or a relative record 

data set: used with keyed access only. 



Figure 13 (Part 1 of 3). OPTCD Options 
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Meaning 

User's argument determines the record to be located, retrieved, 
or stored. 

LRD Last record in the data set is to be located (POINT) or 

retrieved (GET direct); requires OPTCD = BWD. 

FW1) Processing to proceed in a forward direction. 

BWD Processing to proceed in a backward direction; for keyed 

(KEY) or addressed (ADR) sequential (SEQ) or direct (DIR) 
requests; valid for POINT, GET, PUT, and ERASE 
operations; establish positioning by a POINT with 
OPTCD = BWD or by a GET direct with 
OPTCD = (NSP.BWD). When OPTCD = BWD is specified, 
subparameters KGE and GEN are ignored; subparamctcrs 
KEQ and FKS are assumed. 

ASY Asynchronous access; VSAM returns to the processing 

program after scheduling a request so the program can do other 
processing while the request is being carried out. 

SYN Synchronous access; VSAM returns to the processing program 

after completing a request. 

NSP With OPTCD = DIR only, VSAM is to remember its position 

(for subsequent sequential access); that is, the position is not to 
be forgotten unless an ENDREQ macro is issued. 

NUP A data record that is being retrieved will not be updated or 

deleted; sTecord that is being stored is a new record; VSAM 
doesn't remember its position for direct requests into a work 
area. 

L'PI) A data record that is being retrieved may be updated or deleted; 

a record that is being stored or deleted was previously retrieved 
with 0?TCD= UPD; VSAM remembers its position for 
sequential and direct GET requests. When PUT is issued after 
a DIRUPD GET request, PUT causes VSAM to release 
exclusive control. 

KEQ For GET with OPTCD = (KEY.DIR) or (KEY.SKP) and for 

POINT with OPTCD = KEY, the key (full or generic) that you 
provide for a search argument must equal the key or relative 
record number of a record. For a relative record data set, KEQ 
is assumed except for POINT. 



Figure 13 (Part 2 of 3). OPTCD Options 
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Option Meaning 

KGE For the same cases as KEQ, if the key (full or generic) that you 

provide for a search argument doesn't equal that of a record, 
the request applies to the record that has-the next higher key. 
For a relative record data set and POINT, KGE positions to 
the specified relative record number whether the slot is empty 
or not. If the relative record number is greater than the highest 
existing record, EOD is returned. A subsequent PUT will 
insert the record at this position. 

FKS A full key is provided as a search argument. 

GEN A generic key is provided as a search argument; give the length 

in the KEYLEN parameter. 

NWAITX Never take the user's UPAD exit. 

WAITX If OPTCD = S YN and the ACB's MACRF = LSR GSR and 

UPAD exit routing is specified, VSAM takes the UPAD exit at 
points when VSAM would normally issue a WAIT. 

LOC For retrieval, VSAM leaves the data record in the I/O buffer 

for processing; not valid for PUT or ERASE; valid for GET 
with OPTCD = UPD. However, to update the record, you 
must build a new version of the record in a work area and 
modify the request parameter list OPTCD from LOC to MVE 
before issuing a PUT. For keyed-sequential retrieval, 
modifying key fields in the I/O buffer may cause incorrect 
results for subsequent GET requests until the I/O record is 
reread. 

MVE For retrieval, VSAM moves the data record to a work area for 

processing, and for storage, VSAM moves it from the work 
area to the I/O buffer. 



Figure 13 (Part 3 of 3). OPTCD Options 

RECLEN = number 

specifies the length, in bytes, of a data record being stored. This parameter 
is required for a PUT request. 

For GET requests, VSAM puts the length of the record retrieved in this 
field in the request parameter list. It will be there if you update and store 
the record. 

TRANSID = number 

specifics a number that relates modified buffers in a buffer pool. Used in 
shared resource applications and described in the chapter "Sharing 
Resources" in VSAM Administration Guide. 
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Example: RPL Macro 



In this example, an RPL macro is used to generate a request parameter list 
named PARMLIST. 

ACCESS ACB MACRF=( SKP , OUT) , 
DDNAME=PAYROLL 



PARMLIST RPL 


ACB=ACCESS, 






AM=VSAM, 






AREA=WORK, 






AREALEN=125 , 






ARG=SEARCH, 






MSGAREA=MESSAGE, 






MSGLEN=128, 






OPTCD=(SKP,UPD) 


WORK 


DS 


CL125 


SEARCH 


DS 


CL8 


MESSAGE 


DS 


CL128 



Most OPTCD defaults are 
appropriate to assumptions. 



The ACB macro named ACCESS, specifics skip-sequential retrieval for update. 
Further details may be provided on a DD statement named PAYROLL. 

The RPL macro's parameters are: 

• ACB associates the request parameter list with the access method control 
block generated by ACCLSS. 

• AREA and AREALEN specify a work area, WORK, that is 125 bytes long. 

"• ARG specifics that the search argument is defined at SEARCH, ^"he search 
argument is 8 bytes long. 

• MSGAREA and MSGLEN specify a message area, MESSAGE, that is 128 
bytes long. The message area is provided for physical error messages. 

• OPTCD specifics skip-sequential processing and specifics that a retrieved 
record may be updated or deleted. 

Because KEYLEN is not coded, a full-key search is assumed. 
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SCHBFR Macro (Search Buffer) 

The format of the SCHBFR macro is: 



SCHBFR 



|BFRNO = number\ 
,RPL = address 



BFRNO = number 

specifies the number of the buffer VSAM is to search first. The buffers 
preceding it in the buffer pool are not searched. The default is 1 ; that is, 
the first buffer is searched first. (If the number is coded in register notation, 
all registers except 1 and 13 may be used.) 

RPL = address 

specifics the address of the request parameter list that defines the SCHBFR 
request. These RPL parameters have meaning for SCHBFR: 

ACB «■ address 



AREA = address 

If a buffer is found, the area whose address is specified will contain its 
address (OPTCD= LOC) or a copy of its contents (OPTCD = MVE). 

AREALEN- number 

At least 4 with OPTCD = LOC; at least control interval size with 
OPTCD = MVE. 

ARG - address 

ARG gives the address of an 8-byte field that contains the beginning 
and ending control interval RBAs of the range to be searched on. 

ECB = address 



OPTCD - (fASYlSYNULOCI MVE) ) 
TRANSID = number 



All other RPL parameters are ignored. RPLs are assumed not to be 
chained. Control interval access is assumed. 

If the ACB to which the RPL is related has MACRF = GSR, the program 
that issues SCHBFR must be in supervisor state with protection key to 7. 
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SHOWCB Macro (Display Fields of an Access Method Control Block) 

The format of the SIIOWCB macro used to display fields in an access method 
control block is: 



\label\ 


SHOWCB 


ACB = address 
,AREA = address 
,LENGTH = number 
|,OBJECT = DATAIINDEXI 


.FIELDS = (|ACBLEN| |,AVSPAC| 
|,BFRFND||,BSTRNO| 
|,BUFNO| |,BUFRDS| 
|,BUFSP| 

|,CINV| |,DDNA\1E||,ENDRBA1 
|,ERROR| |,EXLST||,FS| 
|,HALCRBA| |,KEVLEN||,LRECL| 
|,MAREA| [,MLEN||,NCIS1 
|,NDELR| |,NEXCP||,NEXT| 
|,NIXL| I,NLOGR||,NRETR| 
|,NUIVV| |,NLPDR||,PASSWD| 
I,SHRP()OL| |,S 1 MS 1 ||,S I RM AX| 
I,SI RNOj |,UIW|) 



The parameters of the SHOWCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that generate valid 
relocatable A-type address constants, in register notation, as S-type address 
constants, and as indirect S-typc address constants. Appendix C, "Operand 
flotation" xm page I€i , 'further ucfines these trpcrand expressions. 

label 

is 1 to 8 characters that provide a symbolic address for the SIIOWCB 
macro. 

ACB = address 

specifies the address of the access method control block whose fields are to 
be displayed. If you used the ACB macro with a label, you can specify the 
label here. The ACB parameter is optional when you wish to display the 
length of an access method control block (FIELDS = ACBLFN). (All 
access method control blocks have the same length, so you need not specify 
the address of a particular one.) 

AREA *= address 

specifies the address of a work area that you are supplying for VSAM to 
display the contents of the fields you specify in the FIELDS parameter. 
The contents of the fields are displayed in the order in which you specify 
them. The area must begin on a fullword boundary. 

LENGTH = number 

specifies the length, in bytes, of the work area that you are providing for 
VSAM to display the indicated fields in. (See the FIELDS parameter for 
the fields that can be displayed and for the length of each field.) If the area 
is not large enough for all the fields, VSAM doesn't display any of their 
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contents and returns a reason code (see "Control Block Manipulation 
Macro Return Codes and Reason Codes" on page 10). 

OBJECT = DATA UXPEX 

specifies whether fields are to be displayed for the data or for the index. 

FIELDS - |ACBLEN||,AVSPACI 

|,BFRFND||,BSTRNO| 

|,BUFND||,BIJFNI| 

|,BUFNO||,BUFRDS| 

|,BL r FSP||,CINVJ 

|,DDNAMEfl,ENDRBA| 

|,ERROR||,EXLST| 

|,FS|J,HALCRBA| 

|,KEYLEN||,LRKCLJ 

|,MAREA||,MLENI 

|,NCIS||,NDELR| 

|,NEXCP||,NEXT| 

1AINSR|[,MXL| 

|,NIOGR||,NRETR| 

|,NSSS||,NUI\V1 

|,NLTDR||,PASSWD| 

(,RKPI(,SHRPOOL| 

|,S'IMSTI|,SIRMAX| 

I,STRNO||,i;i\V]) 

specifics the fields whose contents are to be displayed. Some of the fields 
can be displayed at any time; others only after a data set is opened. The^ 
ones that ca n b e displayed only after a data set is opened can, in the case of 
a kev-sequencect data set that ha s been opened for keyed access, p ertain 
cither to Ihe data ui 10 lite inacx. ace ihc OBJECT parameter. Figure 14 
explains ine Keywords you can code in the FIELDS parameter for an access 
method control block. 



Keyword Fullwords Description of the Field 



ACBLEN 1 



BSTRNO 1 
BUFND 1 



Note: The following fields can be displayed at any 
time. 

Length of an access method control block 
(displaying the length of an access method control 
block gives your program independence from 
changes in the length that may occur from release 
to release of VSAM) 

Number of strings initially allocated for access to 
the base cluster by a path 

Number of I/O buffers to be used for data, as 
specified in the ACB (or GENCB) 



Figure 14 (Part 1 of 4). 



FIELDS Operand Keywords for an Access Method Control 
Block 



1 34 M VS/XA VSAM Administration: Macro Instruction Reference 



SHOWCB-ACB 



Keyword Fullwords 

BUFNI 1 

BUFSP 1 

DDNAME 2 

ERROR 1 



EXLST 1 

MAREA 1 

MLEN 1 

PASSWD 1 

SHRPOOL 1 

STRMAX 1 

STRNO 1 



AVSPAC 1 

BFRFND 1 

BUFNO 1 

BUFRDS 1 

CINV 1 



Description of the Field 

Number of I/O buffers to be used for index entries, 
as specified in the ACB (or GENCB) 

Amount of space specified in the ACB (or 
GENCB) for I/O buffers 

Name of the DD statement that identifies the data 
set 

The code returned by VSAM after the opening or 
closing of the data set (sec "OPEN Macro (Connect 
Program and Data)" on page 107 and "CLOSE 
Macro (Disconnect Program and Data)" on 
page 55). 

Address of the exit list, if any; if none 

Address of the message area, if any; if none 

Length of the message area, if any; if none 

Address of the field containing the password; the 
first byte of the field contains the length of the 
password (in binary) 

Identification number of resource pool to be used 
for LSR processing 

Maximum number of strings concurrently active 

"Number of requests for which VSAM is prepared 
to remember its position in the data set 

Note: 'Ilie following fields can be displayed only 
after the data set is opened. 

Amount of available space in the data component 
or index component, in bytes 

Number of successful look-asides 

Number of I/O buffers actually in use for the data 
component or index component 

Number of buffer reads 

Control interval size for the data component or 
index component 



Figure 14 (Part 2 of 4). FIELDS Operand Keywords for an Access Method Control 

Block 
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Keyword Fullwords 
ENDRBA 



FS 
HALCRBA 

KEYLEN 

LRECL 

NCIS 

NDELR 

NEXCP 

NEXT 

NINSR 

MXL 

NLOGR 

NRE'IR 

NSSS 



Description of the Field 

Ending RBA of the space used by the data 
component or index component; not the RBA of 
any record in the data set, but of the last used byte 
in the data set 

Number of free control intervals per control area in 
the data component (0 for OBJECT = INDEX) 

High-allocated RBA; the relative byte address of the 
end of the data component (OBJECT = DATA) or 
the index component (OBJECT = INDEX) 

Length of the key of reference of the key field of 
data records in the data component (whether 
OBJECT = DATA or INDEX) 

Length of data records in the data component 
(maximum length for variable-length data records) 
or of index records in the index component (control 
interval length minus 7) 

Number of control intervals that have been split in 
the data component (0 for OBJECT = INDEX) 

Number of records that have been deleted from the 
data, component (0 for OBJECT' » INDEX> 

Number of EXCP macros that VSAM has issued 
for access to the data component or index 
component. 

Number of extents now allocated to the data 
component or index component (the maximum 
that can be allocated in 123) 

Number of records that have been inserted into (or 
added to) the data component (0 for 
OBJECT = INDEX) 

Number of levels in the index component (0 for 
OBJECT = DATA) 

Number of records in the data component or index 
component 

Number of records that have ever been retrieved 
from the data component (0 for 
OBJECT= INDEX) 

Number of control areas that have been split in the 
data component (0 for OBJECT = INDEX) 



Figure 14 (Part 3 of 4). FIELDS Operand Keywords for an Access Method Control 

Block 
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Keyword 


Fullwords 


NUIW 


1 


NUPDR 


1 



RKP 



STMST 



UIW 



Description of the Field 

Number of writes not initiated by the user 

Number of records in the data component or index 
component that have ever been updated 

Displacement of the key of reference of the key field 
from the beginning of a data record (whether 
OBJECT= DATA or INDEX) 

System time stamp, which gives the time and day of 
the last time the data component or index 
component was closed, with bit 51 (counting from 
at the left) equivalent to one microsecond and bits 
52 through 63 unused 

Number of user-initiated writes 



Figure 14 (Part 4 of 4). FIELDS Operand Keywords for an Access Method Control 

Block 



Example 1: SHOWCB Macro (Display an Access Method Control Block) 



In this example, a SI IOWCB macro is used to display fields in an access method 
control block. The fields displayed (KEYLEN, LRECL, and RKP) permit the 
program to modify variables to process any one of a number of data sets that 
have different sized key fields and records and different placements of key field in 
a record. 





SHOWCB 


ACB=CONTROL, 
AREA=DI SPLAY, 
FIELDS=( KEYLEN, 
LRECL, RKP), 
LENGTH=12 


DISPLAY 


DS 


OF 


KEYLEN 


DS 


F 


LRECL 


DS 


F 


RKP 


DS 


F 



Align on fullword boundary. 



The SHOWCB macros parameters are: 

• ACB specifics the address of the access method control block to be displayed. 

• AREA specifics that the area to be used to display access method control 
block fields is to begin on a fullword boundary. 

• FIELDS specifies that the KEYLEN, LRECL, and RKP fields are to be 
displayed. 

• LENGTH specifies that the length of the area to be used for the display is 12 
bytes, enough to accommodate the specified fields. 
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This display enables the program to set up its variables for the particular data set 
it has opened. 



Example 2: SHOVVCB Macro (Display an Exit List Address) 



In this example, a SIIOWCB macro is used to get the address of an exit list by 
displaying the address in an access method control block that uses the exit list. 

SHOWCB ACB=address, 
AREA=address , 
FIELDS=EXLST, 
LENGTH=4 

The SIIOWCB macro's parameters are: 

• ACB specifies the address of an access method control block from which the 
address of an exit list is to be displayed. 

• AREA and LENGTH specify an area and length, 4 bytes, to be used to 
display the address of the exit list. 

• FIELDS specifies that the EXLST field in an access method control block is 
to be displayed. 
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SHOWCB Macro (Display Fields of an Exit List) 

The format of the SHOWCB macro used to display fields in an exit list is: 



[label\ 


SHOWCB 


EXIST "address 
,AREA = address 
,LENGTH = number 

,FIELDS = (|EODAD| |,EXLLEN| IJRNAD] 
|,LERAD||,SYNAD|) 



The subparamctcrs of the SHOWCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that generate valid 
relocatable A-typc address constants, in register notation, as S-typc address 
constants, and as indirect S-type address constants. Appendix C, "Operand 
Notation" on page 181, further defines these operand expressions. 

label 

is 1 to 8 characters that provide a symbolic address for the SHOWCB 
macro. 

EXIST "address 

specifies the address of the exit list whose fields are to be displayed. If you 
used the EX EST macro with a label, you can specify the label here. The 
EXLST parameter is optional only when you want to display the length 
that an exit list can have (see FIELDS = EXLLEN below). The SHOWCB 
macro does not support the UPAD user exit. 

AREA = address 

specifies ihc address of a work area that you arc supplying for VSAM to 
display the contents of the fields you specify in the FIELDS parameter. 
The contents of the fields are displayed in the order you specify them. The 
area must begin on a fullword boundary. 

LENGTH = number 

specifies the length, in bytes, of the work area that you are providing for 
VSAM to display the indicated fields in. Each exit-list field requires a 
fullword. If the area is not large enough for all the fields, VSAM doesn't 
display any of their contents and returns an error code (see "Control Block 
Manipulation Macro Return Codes and Reason Codes" on page 10). 

FIELDS - (|EODAD||,EXLLEN||,JRN AD| 
|,LERAD||,SYNAD|) 

specifics the values to be displayed, as follows: 

EODAD 

specifies that the address of the end-of-data-set routine is to be 
displayed. 

EXLLEN 

specifies that the length of the exit list indicated in the EXLST 
parameter or if EXLST is omitted, the maximum length an exit 
length can have, is to be displayed. 
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JRNAD 

specifies that the address of the journalizing routine is to be displayed. 

LERAD 

specifies that the address of the logical error analysis routine is to be 
displayed. 

SYNAD 

specifies that the address of the physical error analysis routine is to be 
displayed. 

You can use SIIOWCB to display the address of an exit routine only if the exit 
routine is indicated in the exit list. If it isn't, the SIIOWCB request will fail. Use 
TESTCB to test whether an entry for a given exit type is present in the exit list 
and to find out whether the exit is active and whether the routine is to be loaded. 



Example: SHOVVCB Macro (Display the Length of an Exit List) 



In this example, a SIIOWCB macro is used to display the maximum length of an 
exit list. The maximum length of an exit list is subsequently used in a GENCB 
macro to get virtual storage for an exit list. 

SHOWCB AREA=LENGTH, 

FIELDS=EXLLEN, 
LENGTH=4 



L 0, LENGTH 

GETMAIN R,LV=(0) 
LR 2,1 



GENCB 



BLK=EXLST, 

LENGTH=(*> 
LENGTH) , 
WAREA=(2) 



Amount of storage for 
GETMAIN. 



Address of storage for 
GENGB. 

Indirect notation for 
length of work area. 



LENGTH DS 



Contains the length of 
GENCB' s work area. 



The SHOWCB macro's parameters are: 

• AREA and LENGTH specify the area, which begins on a fullword 
boundary, and its length, four bytes, that is to be used for the display. 

• FIELDS specifies that the maximum length of an exit list is to be displayed. 
Because only EXLLEN is specified, the EXLST parameter is omitted. 

The GENCB macro specifies a work area in which an exit list is to be generated. 
The length of the work area is located at LENGTH, where the maximum length 
of an exit list was put as a result of the SHOWCB macro. 
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SHOWCB Macro (Display Fields of a Request Parameter List) 



The format of the SHOWCB macro used to display fields in a request parameter 
list is: 



\Iabel\ 


SHOWCB 


RVL = address 

,AREA = address 

,LENGTH = number 

.FIELDS = (| ACB||,AIXI>C)|,AREA|j,AREALEN| 

|,ARG||,ECB||,FDBK||,ITNCD| 

|,KEYLEN||,MSGAREA| 

|,MSGLEN| 

|,NXTRPL||,RBA| 

|,RECLEN| 

|,RPLLEN| 

|,TRANSID|) 



The parameters of the SHOWCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that generate valid 
relocatable A-typc address constants, in register notation, as S-typc address 
constants, and as indirect S-type address constants. Appendix C, "Operand 
Notation" on page 181, further defines these operand expressions. 

label 

is 1 to 8 characters that provide a symbolic address for the SHOWCB 
macro. 

RPL = address 

specifics the address of the request parameter list whose fields arc to be 
displayed. If you used the RPL macro with a label, you can specify the 
label here. The RPL parameter is optional when you want to display the 
length of a request parameter list (FIELDS = RPLLEN). (All VSAM 
request parameter lists have the same length, so you need not specify the 
address of a particular one.) 

AREA =. address 

specifics the address of a work area that you arc supplying for VSAM to 
display the contents of the fields you specify in the FIELDS parameter. 
The contents of the fields arc displayed in the order you specify them. The 
area must begin on a full word boundary. 

LENGTH = number 

specifics the length, in bytes, of the work area that you arc providing for 
VSAM to display the indicated fields in. Each request parameter list field 
requires a fullword. If the area is not large enough for all the fields, VSAM 
doesn't display any of their contents and returns an error code (see 
"Control Block Manipulation Macro Return Codes and Reason Codes" on 
page 10). 
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FIELDS « (|ACB|1,AIXPCH,AREAI|,AREALEN|I,ARG| 
I,ECB||,FDBK||,FTNCD|I,KEYLENI 
|,MSGAREA||,MSGLEN| 
|,NXTRPL||,RBA|I,RECLEN| 
I,RPLLEN|I,TRANSIDI) 

specifics the fields whose contents are to be displayed. Figure 15 on 
page 142 explains the keywords you can code in the FIELDS parameter for 
a request parameter list. Some fields (each indicated by an asterisk (*) in 
Figure 15) are meaningful only if the requests have been completed; 
therefore, you must wait until the request has completed (for example, by 
issuing a CHECK if the request is asynchronous) before issuing SIIOWCB. 



Keyword 
ACB 

AIXPC* 
AREA 

AREALEN 

ARC 

ECB* 

FDBK* 



Fullwords Description of the Field 



FUSCD* 



Address of the access method control block that 
relates the request parameter list to the data 

Number of alternate index pointers 

Address of the work area that the program uses to 
process a data record for the access as defined by 
the request parameter list 

Length of the work area whose address is given in 
AREA 

Address of the field containing a search argument, 
if search, arguments are being used. 

Address of an event control block, if any, in which 
VSAM indicates the completion of requests 
defined by the request parameter list 

Reason code that VSAM puts into the feedback 
field to describe the error detected for the 
preceding request. (The meaning of this code 
depends on the contents of register 15, which 
indicates whether the request was successful or 
failed because of a logical or physical error. See 
"Record Management Return Codes and Reason 
Codes" on page 13) 

Code that describes the function in which a logical 
or physical error occurred; indicates whether the 
upgrade set may have been modified incorrectly by 
the preceding request (The meaning of this code 
depends on the contents of register 15, which 
indicates whether the request was successful or 
failed because of a logical or physical error. See 
"Record Management Return Codes and Reason 
Codes" on page 13) 



Figure IS (Part I of 2). 



FIELDS Operand Keywords for a Display Request Parameter 
List 
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Keyword Fullwords 

KEYLEN 1 

MSGAREA* 1 

MSGLEN 1 

NXTRPL 1 



RBA' 



1 



RECLEN* 1 

RPLLEN 1 
TRAXSID 1 



Description of the Field 

Length of the search argument, if a generic key is 
used for a search argument 

Address of the area, if any, into which VSAM puts 
physical error messages 

Length of the message area, if any 

Address of the next request parameter list, if 
another one is chained to this one 

Relative byte address of the most recently 
processed record; you could use it to record the 
RBAs of records that you arc retrieving or storing 
sequentially or by key 

Length of the data record, access to which is 
defined by the request parameter list 

Length of a request parameter list 

Number that relates modified buffers in a buffer 
pool; described in VSAM Administration Guide 



Figure 15 (Fart 2 of 2). FIELDS Operand Keywords for a Display Request Parameter 

List 
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Example: SHOWCB Macro (Display a Physical Error Message) 



In this example, a SHOWCB macro is used to display a physical error message. 
This example assumes that there is no SYNAD routine (or the SYNAD exit is 
inactive), in which case, VSAM returns control to your program following the 
last executable instruction if a physical error occurs. Register 1 5 indicates a 
physical error (12), and the feedback field in the request parameter list contains a 
code identifying the error; the message area contains more details about the error. 
Register 1 points to the request parameter list. 



REQUEST RPL 



MSGAREA= 

MESSAGES, 

MSGLEN=128 



SHOWCB AREA=MSGADDR, 

FIELDS=MSGAREA, 

LENGTH=4, 

RPL=REQUEST 

LTR 15,15 

BNZ CHECKO 



CHECKO 



Display failed. 



MESSAGES DS 



MSGADDR DS 



CL128 



For VSAM to give you a 
detailed message about 
a physical error. 

For displaying the 
address of the message 
area with SHOWCB. 



The RPL macro in this example provides for a message area, MESSAGES, of 
128 bytes to be used for any physical error message. 

The SHOWCB macro's parameters are: 

• AREA and LENGTH specify a 4-byte area, MSGADDR, to be used for 
displaying the address of the message area for the associated request 
parameter list. 

• FIELDS specifies that the address of the message area is to be displayed. 

• RPL specifics the name, REQUEST, of the request parameter list for which 
the message area address is to be displayed. 
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TESTCB Macro (Test Fields of an Access Method Control Block) 



Only one keyword can be specified each time you issue TESTCB. The format of 
the TESTCB macro used to test a field in an access method control block is: 



\label\ 


TESTCB 


ACB = address 
\,ERET = address) 
|,OBJECT= DATA|INDEX| 
,{ ATRB = (|ESDS||,KSDS|[,LDSH,REPLI 
|,RRI)S||,SPAN||,SS\VD||,\VCK|| 

ATRB = tfNQ| 

CATALOG = YES|NO| 

CRA = SCRA|UCRA| 

MACRF = (IADRJI, AIX||,CFX||,CNV||,I)DN| 






|,DFR||,DIRH,DSN!I,GSR1|,ICI||,IN| 
I,KEY||,LSR||,NCI||,NFD||,NFX||,MSI 
|,NRM||NRS|i,\SR||,NUB||,OU I ||,RST1 
|,SEQ||,SIS||,SKP||,UBF|)| 

OFLAGS = OPEN| 

OPENOBJ = PATH|BASE| AIX| 

ACBLEN = /iu/72&er| 

AVSPAC = number] 

BSTRNO - number] 

BUFND = number] 

KUEXl = number] 

BUFNO = number] 

BUFSP = number] 

CINV- number] 

imXAME**Jiiname\ 

EM)RBA = number] 

ERROR = number] 

EXLST = address] 

FS = number] 

KEYLE\= number] 

LRECL = number] 

M ARE A - address] 

MLEN = number] 

KC\S = number] 

NDELR = number] 

NEXCP = number] 

NEXT - number] 

NINSR = /iwm6er| 

N\XL = number] 

NLOGR = number] 

NRETR = number] 

NSSS = number] 

NUPDR = number] 

PASSWD = address] 

RKP = number] 

SHRPOOL = number] 

STMST = address] 

STRNO = number) 
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The subparameters of the TESTCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that generate valid 
relocatable A-type address constants, in register notation, as S-type address 
constants, and as indirect S-type address constants. Appendix C, "Operand 
Notation" on page 181, further defines these operand expressions. 

ACB = address 

specifies the address of the access method control block whose information 
you want to test. You may omit it only if you're testing the length of an 
access method control block (ACBLEN = number). (All VSAM access 
method control blocks have the same length.) 

ERET = address 

specifies the address of a routine to which VSAM is to give control if, 
because of an error, it is unable to test for the condition you specify. For 
example, testing AVSPAC in an access method control block for an 
unopened data set would fail. VSAM indicates in register 15 whether it 
could do the test and, if not, indicates in register the reason it couldn't. 
(The reasons are discussed under "Control Block Manipulation Macro 
Return Codes and Reason Codes" on page 10.) A failure trying to execute 
TESTCB indicates a basic logical problem in the processing program, so 
the error routine would probably issue an ABEND. If it lets the program 
continue, it must branch to the continuation point itself, and not return to 
VSAM. 

OBJECT - DATA I INDEX| 

specifies whether you want to test a field for data or for index. 

ATRB = (|ESDS||,KSDS||,LDS| 
I.REPLI 
I,RRDS| 
|,SI»AN| 
|,SSW1)| 
l,WCK|) 

specifies, for an open data set, the attribute that is to be tested for, as 
follows: 

ESDS 

entry-sequenced data set 

KSDS 

key-scquenccd data set 



LDS 



linear data set 

Note: When specified, LDS must be the only parameter indicated by 
ATRB. All other parameters will be ignored and a binary test will be 
performed that indicates whether the data set is a linear data set 
(return code 0) or not (return code 1). 
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REPL 

some portion of the index is replicated 

RRDS 

relative record data set 

SPAN 

data set contains spanned records 

SSWD 

sequence set is adjacent to the data 

WCK 

write operations for the data set are being verified 

ATRB-UNQ 

specifics, for an open alternate index or path, that the alternate index 
requires unique keys. The test for ATRB = UNQ must be made with a 
separate TESTCB macro. VSAM examines the path control blocks for the 
UNQ attribute; and also examines the base cluster's control blocks for the 
other attributes. If other attributes arc tested for, VSAM examines the base 
cluster's control blocks for all attributes: The test for ATRB= UNQ would 
give inaccurate results when applied to the base cluster's control blocks. 

CATALOG -YESINO 

specifics that a test is to be made to determine, any time, whether or not 
the access method control block specifics a catalog data set. 

CRA = SCRA|UCRA 

specifies that a test is to ^c made to determine, any time, whether catalog 
recovery area control blocks are to be built in system storage or user 
storage. 

M ACRF - ([ADR|[,AIX||,CFX1 

|,CNV||,DDN| 

|,DFR||,DIR| 

|,DSNH,GSR] 

|,ICI||,INI 

I,KEY|I,LSR] 

|,N<T||,M>E| 

|,NFX|I,NISI 

|,NRM||,NRS) 

|,NSR||,NUB| 

|,OUT||,RST| 

|,SEQ||,SIS| 

|,SKP||,UBF| 

specifies that a test is to be made to determine, at any time, what 
subparamctcr or combination of subparameters is being used for processing. 

OFLAGS = OPEN 

specifies that a test is to be made to determine, after open, whether the data 
set identified by the control block has been opened. 
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OPENOBJ - PATH|BASE| AIX 

specifies that a test is to be made to determine, after open, whether an 
opened object is a path, a base cluster, or an alternate index. 

The remaining parameters represent fields in an access method control block that 
can be compared with the value specified. These fields are the same as those that 
can be displayed by using the SHOWCB macro and are described in Figure 14 
on page 134. 

If you omit a routine to handle error conditions, you can examine register 15 
following TESTCB by using a branch table, for example, but don't alter the 
PSW condition code that VSAM set to indicate the result of a test until you've 
had a chance to test it. 



Example: TESTCB Macro (Test for Data Set Attributes) 



In this example, a TESTCB macro is used to determine whether a data set is a 
key sequenced or an entry-sequenced data set. 



LIST 



RPL 



SHOWCB AREA=DATAFACT, 
FIELDS=ACB, 
LENGTH=4, 
RPL=LIST 



LTR 

BNZ 



15*15 
CHECKO 



TESTCB ACB=(*, 

DATAFACT) , 
ATRB=KSDS, 
ERET=CHECKO 



BE 



KEYSEQ 
CHECKO 



DATAFACT DS 



KEYSEQ 



Is the data set key 
sequenced? 



Yes. 

Data set is key sequenced. 
Display or test failed. 



For displaying address of 
access method control 
block. 



The SHOWCB macro's parameters are: 

• AREA and LENGTH specify a 4-byte area, DATAFACT, aligned on a 
fullword boundary, to be used for the display. 

• FIELDS and RPL specify that the address of the access method control 
block in the LIST request parameter list is to be displayed. 

The TESTCB macro's parameters are: 
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• ACB specifics that a field in the access method control block, the address of 
which is located at DATAFACT, is to be tested. The SHOWCB macro put 
the address of the access method control block at DATAFACT. 

• ATRB specifies that the access method control block is to be tested to 
determine whether it is a key-sequenccd data set. 

• FRET specifies that a routine named CIIECKO is to be given control if an 
error occurs that makes it impossible to make the test. 

There is no need to examine the feedback field in an EODAD routine, because it 
can be assumed to contain the end-of-data-set indication. 
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TESTCB Macro (Test Fields of an Exit List) 

The format of the TESTCB macro used to test fields in an exit list is: 



[label! 


TESTCB 


EXLST =» address 
|,ERET= address] 

,{EODAD - {0|<|a<Wrew|I,A|NJl,L|)} | 

JRNAD - {0|(|a^rejj||,A|N||,LI)} 1 

LERAD- {0|(ia^rew||,A|NH,L|)}| 

SYNAD- {0|(|a<fc/re«|I,A|N||,L|)J} 

|,EXLLEN = number] 



The parameters of the TESTCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that generate valid 
relocatable A-typc address constants, in register notation, as S-typc address 
constants, and as indirect S-type address constants. Appendix C, "Operand 
Notation" on page 181, further defines these operand expressions. 

label 

is 1 to 8 characters that provide a symbolic address for the TESTCB macro. 

EXLST = address 

specifies the address of the exit list whose information you want to test. 
You may omit it only if you're testing the maximum length of an exit list 
(EXLLEN= number)*. The TESTCB macro does not support the UPAD 
user exit. 

ERET = address 

specifics the address of a routine to which VSAM is to give control if, 
because of an error, it is unable to test for the condition you specify. For 
example, testing AVSPAC in an access method control block for an 
unopened data set would fail. VSAM indicates in register 15 whether it 
could do the test and, if not, indicates in register the reason it couldn't. 
(The reasons are discussed under "Control Block Manipulation Macro 
Return Codes and Reason Codes" on page 10.) A failure trying to execute 
TESTCB indicates a basic logical problem in the processing program, so 
the error routine would probably issue an ABEND. If it lets the program 
continue, it must branch to the continuation point itself, and not return to 
VSAM. 

EODAD - {0|(|tfrfdrew||,A|NII,L|)} | 

JRNAD = {0|(larf</rett||,A|N||,L|)} | 

LERAD = {0\([address}lA\X\[tD}\ 

SYNAD= {0\([address\[MNU,L\)} 

specifies the exit about which you are asking a yes-no question. If you 
code more than one parameter for an exit name, each must equal the 
corresponding value in the control block for you to get an equal condition. 
The values that can be tested are: 







specifies that a test is to be made to determine whether an entry is 
provided for the exit in the exit list. 
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address 

specifies that a test is to be made to determine whether this is the 
address of the exit. Tests for an address result in an equal, unequal, 
high, low, not-high, or not-low condition. Tests for a combination of 
an address and A, N, or L result in an equal or unequal condition. 

A|N 

specifies that a test is to be made to determine whether an exit is 
active (A) or not active (N). Tests for A or N result in an equal or 
unequal condition. 



specifics that a test is to be made to determine whether the address is 
the location of an 8-byte field containing the name of a module to be 
loaded rather than the entry point of the routine. Tests for L result in 
either an equal or unequal condition. 

EXLLEN ■ number 

specifics cither the maximum length that an exit list can have (if you don't 
code the IiXI^ST parameter) or the actual length of the exit list indicated by 
the EXIiiT parameter. If you specify an exit, you may not also specify 
EXLLEN; if you specify EXLLEN, you may not also specify an exit. 

If you omit a routine to handle error conditions, you can examine register 15 
following TESTCB by using a branch table, for example, but don't alter the 
PSW condition code that VSAM set to indicate the result of a test until you've 
had a chance to test it. 



Example: TESTCB Macro (Use a Branch Table) 



In this example, a TESTCB macro is used to test whether ENDPROC is the 
routine supplied for the EODAD exit in the exit list EXITS, and whether the 
EODAD exit is active. A branch table is used to determine whether the test is 
successful. 

TESTCB EODAD=(ENDPROC,A) Is ENDPROC supplied and is 

EXLST=EXITS the exit active? 
B *+4(15) 

If the test was made successfully, register 15 contains and the next instruction is 
executed. 

B TEST1 

If it was unsuccessful, register 15 contains 4 and the next instruction is executed. 

ABEND 2, DUMP 

TEST1 BNE NO 

YES ... Yes; ENDPROC is supplied 

and active. 

NO ... ENDPROC isn't supplied, or 

the exit isn't active. 
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TESTCB-RPL 



TESTCB Macro (Test a Request Parameter List) 



The format of the TESTCB macro to test fields in a request parameter list is: 



[label] 


TESTCB 


RPL = address 

|,ERET = address] 

,{A!XFLAG = AIXPKP| 

AIXVC = number] 

FfNCD- number] 

IO = COMPLETE| 

OPTCD - (IADR||,ARD||,ASYH,BWD| 
l,CNV||,DIR||,FKS|I,FWD| 
I,GEN||,KEQl|,KEY||,KGE|(,LOC| 
|,LRI)|I,MVE||,NSP||,NLP||,SEQ| 
[,SKP||,SYN|[,UPD|)| 

ACB = address] 

AREA = address] 

AREALVJN = number] 

ARG = address] 

ECB = address] 

FDBK *» number] 

KEYLEN= number] 

MSGAREA - address] 

MSGLEN = number] 






>iXTRPL = addressl 
RBA = number] 
RECLEN- number] 
RPLLEN = number] 
TRANSID- number] 



The parameters of the TESTCB macro can be expressed as absolute numeric 
expressions, as character strings, as codes, as expressions that generate valid 
relocatable A-typc address constants, in register notation, as S-type address 
constants, and as indirect S-type address constants. Appendix C, "Operand 
Notation" on page 181, further defines these operand expressions. 

where: 



label 

is 1 to 8 characters that provide a symbolic address for the TESTCB macro. 

RPL = address 

specifies the address of the request parameter list whose information you 
want to test. You may omit it only if you're testing the length of a request 
parameter list (RPLLEN = number). (All request parameter lists have the 
same length.) 

ERET = address 

specifies the address of a routine to which VSAM is to give control if, 
because of an error, it is unable to test for the condition you specify. For 
example, testing AVSPAC in an access method control block for an 
unopened data set would fail. VSAM indicates in register 15 whether it 
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TESTCB-RPL 

could do the test and, if not, indicates in register the reason it couldn't. 
(The reasons are discussed under "Control Block Manipulation Macro 
Return Codes and Reason Codes" on page 10.) A failure trying to execute 
TESTCB indicates a basic logical problem in the processing program, so 
the error routine would probably issue an abend. If it lets the program 
continue, it must branch to the continuation point itself, and not return to 
VSAM. 

AIXFLAG = AIXPKP 

specifics that prime-key pointers are used rather than RBAs. 

AIXPC - number 

specifics the pointer count. 

FTNCD = number 

specifies whether the upgrade set is correct or may have been modified by a 
request. These codes are described under "Component Codes 
(RPLCMPON)" on page 14. 

IO- COMPLETE 

specifics that a test is to be made to determine whether an asynchronous 
request has been completed. (When you issue a CHECK macro, you 
suspend processing until a request has been completed if it hasn't yet been 
completed.) 

OPTCD = (|,ADR||,ARD|| ) ASY||,BVVD||,CNT||,DIR||,FKS| 
|,F\Vl)||,GEN||,KEQ||,KEY||,KGE||,LOC|I,LRDI 
|,M\E||,NSPj|,NLP||,SEQ|l,SKPH,SYN||,L'PI)| 

specifics that a test is to be made to determine what subparamctcr or 
combination of subparamcters is being used for the request. See Figure 17 
on page 1 84 for a description of these subparameters. 

1 he remaining parameters specify fields in a request parameter list and values; the 
contents of a field are to be compared to the specified value. These fields are the 
same as those that can be displayed by using a SIIOWCB macro. (See Figure 15 
on page 142 for an explanation of these fields.) Fields can be tested at the same 
time they are displayed. 

You may specify only one keyword. If you code a list of option codes (for 
example, OPTCD = (KEY,DIR)), each of them must equal the corresponding 
value in the control block for you to get an equal condition. 

If you omit a routine to handle error conditions, you can examine register 15 
following TESTCB by using a branch table, for example, but don't alter the 
PSW condition code that VSAM set to indicate the result of a test until you've 
had a chance to test it. 
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TESTCB-RPL 



Example: TESTCB Macro (Test a Request Parameter List) 

TESTCB RPL=(3), 
RECLEN=80 



CHANGE 



NOCHNGE 



BE 



NOCHNGE 



Because the record length in 
the request parameter list was 
not 80, the length indicator 
must be modified so that it 
is 80. 

Because the record length in 
the request parameter list was 
80, no change is required. 



The TESTCB macro's parameters arc: 

• RI'L specifics that the address of the request parameter list to be tested is 
contained in register 3. 

• RECLEN specifics that the record length indicated in the request parameter 
list is to be tested to determine whether it is 80. 
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VERIFY 
VERIFY Macro (Synchronize End of Data) 

The format of the VERIFY macro is: 



\label\ 


VERIFY 


RI'L" 5 address 
I,ACTION«REFRESH| 



where: 

label 

is 1 to 8 characters that provide a symbolic address for the VERIFY macro. 

RPL- address 

specifies the address of the request parameter list that defines this VERIFY 
request. You may specify the address in register notation (using a register 
from 1 through 12, enclosed in parentheses) or specify it with an expression 
that generates a valid relocatable A-typc address constant. 

The following parameter and subparamctcr arc required for VERIFY: 

In the RPL, OPTCD - (CNV,...) must be specified. 

ACTION- REFRESH 

specifics that the VSAM control blocks arc to be updated from the catalog 
after an attempt has been made to verify the high-used RBA. For a data 
set that has been extended, VERIFY with ACTION- REFRESH will 
invoke end of volume processing to update the control block structure, 
reflecting the new extents. 

If you do not specify ACTION — REFRESH for an extended data set, you must 
close the data set and reopen it to obtain new extent information before you can 
verify it. 

Any attempt to issue the VERIFY macro against a linear data set (EDS) will 
result in a logical error (return code 253 in the feedback field of the RPL). 

After verifying a data set, positioning must be established with a POINT macro 
or with a GET macro with RPL OPTCD = DIR. 
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WRTBFR 

WRTBFR Macro (Write Buffer) 

The format of the WRTBFR macro is: 



WRTBFR 



RPL = address 

,TYPE = {ALL|CHK|DRBA|DS|LRUOerce/*0|TRN} 



RPL = address 

specifies the address of the request parameter list that defines the WRTBFR 
request. An RPL need not be built especially for the 
WRTBFR-WRTBFR may use an inactive RPL that defines other 
request(s) (GET, PUT, and so forth) for a data set that is using the 
resource pool. The following RPL parameters have meaning for 
WRTBFR: 

ACB =» address 
ARG = address 

For TYPE= DRBA, the address of a 4-byte field that contains the 

RBA to be located and written. 

ECB =» address 

OPTCD={ASY|SYN} 

WRTBFR can be issued synchronously (SYN) or asynchronously 
(ASY). A CTIECKTor ENDREQ must be issued to synchronize an 
asynchronous WRTBFR request. 

TRANSID - number 

Specifics a number from to 31. 

All other RPL parameters are ignored. RPLs are assumed not to be 
chained. 

If the ACB to which the RPL is related has MACRF = GSR, the program 
that issues WRTBFR must be in supervisor state with protection key to 
7. 

TYPE= {ALL|CIIK|l)RBA|DS|LRU(peire/i/)|TRN} 

specifies which buffers are to be written. 

| Note: Before using WRTBFR TYPE = CHK|DRBA|TRN, be sure to 

I release all buffers. VSAM defers processing until all buffers are released. 

I For details about releasing buffers, see VSAM Administration. 

ALL 

I specifies that all modified unwritten index and data buffers in each 

I buffer pool in the resource pool are to be written. No buffers will be 

I invalidated. Closing all the data sets that use a resource pool causes 

I the same buffers to be written. 
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WRTBFR 

CHK 

is as TRN (below), but, if an error occurs in writing buffers, 
transaction IDs continue to be associated with the buffers. 
WRTBFR TYPE = CHK could be used by a checkpoint routine to 
record checkpoint information and leave buffers for which an error 
occurred as they were for continued processing. 

DRBA 

specifics that one of the data set's data buffers is to be written. The 
buffer to be written is identified with the RBA pointed to by the RPL 
ARG address. 

DS 

specifies that, for the data set defined by the ACB to which the 
WRTBFR's RPL is related, all modified unwritten index and data 
buffers are to be written and all buffers are to be marked empty, i.e., 
invalidated. Therefore, WRTBFR TYPE = DS should be issued only 
after all VSAM requests for the data set have been quiesced. 
Otherwise, unpredictable results may occur. 

LRU(pcrcent) 

specifics that some of the modified buffers in each buffer pool in the 
resource pool are to be written. The percent is the percentage of 
buffers in each pool that are to be examined for possible writing. The 
least recently used buffers arc examined. (If percent is coded in 
register notation, only registers 1 and 13 may not be used.) 

TYPE = LRU is used for writing some modified buffers, without 
respect to m -particular data set or transaction ID, to ensure that 
buffers will be available for GET requests (without having to wait for 
buffers to be written). 

TRN 

specifies that all buffers in a buffer pool that have been modified by 
requests with the transaction ID specified in the WRTBFR's RPL are 
to be written. Transaction IDs are no longer associated with these 
buffers if WRTBFR completes successfully. 



Chapter 2. VSAM Macro Formats and Examples 157 



Appendix A. Format of Macros 



For easy reference, the formats of all the macros described in this book are 
repeated here in alphabetic order. 



ACB (Generate an Access Method Control Block at Assembly lime) 



[label] 


ACB 


IAM-VSAMI 

|,BSTRNO- number] 

|,BUFND = number] 

|,BUFNI - number] 

[MVVSV- number] 

I.CATALOG -fYESINOll 

|,CRA={SCRA|UCRA}| 

IDDSAME-ddnamel 

IVXIST* address] 

|,MACRF - (IADRII.CNVH.KEYI 

I.CFXINFX1 

|,DI)\|1)SN| 

|,DFR|M>FJ 

|,DIR||,SE2||,SKP| 

|,ICI1NQ| 

l,IN|l,OUT| 

|,MS|SIS| 

|,NRM|AIXI 

|,NRS|RST| 

1,NSR|LSR|GSR| 

I,NUB|UBF|)| 
IM AREA = address] 
|,M LEN ■» number] 
\,VASS\VD = address] 
|,RMODE3I - (ALLIBUFFICBINONEM 
|,SHRPOOL«= {Q\number}] 
|,STRNO = number] 



ACQRANGE (Stage Data) 



\labeh ACQRANGE RPL- address 
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BLDVRP (Build a VSAM Resource Pool) 



BLDVRP 


BUFFERS = {size(number)jize{nwnber),.,.) 




(,FIX« {BFR|IOB|(BFR,IOB)}| 




|,KEYLEN = /<?*£f/t| 




[,RMODE3l = fALLIBUFFlCBINONEH 




I,SHRPOOL- {0\number}\ 




I,MODE={24|31}| 




,STRNO = number 




f,TYPE= fLSR|,DATA|INDEXHGSR)| 



CHECK (Suspend Processing) 



[labeli 


CHECK 


RPL=* address 



CLOSE (Disconnect Program and Data) 



\labeli 


CLOSE 


(address\,(options)\...\ 
I,MODE={24|3I}| 
|,TYPE = T| 



CNVTAD (Convert Address) 



\/abe!\ 


CNVTAD 


RPL = address 



DLVRP (Delete VSAM Resource Pool) 



DLVRP 



TYPE-(LSRJGSR) 
|,MODE={24|3l}| 
|,SHRPOOL= {0\number}\ 



ENDREQ (Terminate a Request) 



ERASE (Delete a Record) 



\labe!\ 


ENDREQ 


RPL = address 



[!abel\ 


ERASE 


RPL = address 
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EXLST (Generate an Exit List at Assembly Time) 



[label] 


EXLST 


IAM = VSAM| 

|,EODAD - (address\,A\K][ y L])] 
|,IOPID = (address)] 
I^JRNAD - (address[,A\X]m)] 
|,LERAD = (a<tarew|,A|N||,L|)| 
|,SYNAD - (arf<fo»tt|,A|N|(,L|)| 
|,UPAD = (arf</reu|,A|N||,L|)) 



GENCB (Generate an Access Method Control Block at Execution Time) 



[label] 


GENCB 


BLK = ACB 
I.AM-VSAMI 
|,BSTRNO = *wm6e/1 
|,BUFND = number] 
|,BUFNI = number] 
|,BUFSP- number] 
I.CATALOG- fYESINOll 
ICOPIVS' number] 
|,CRA- {SCRA|UCRA}| 
|,DDNAME- ddname] 
|,EXLST- address] 
|,LENGTII = number] 
IXOC - f BELOWI ANYII 
(JVfACRF- ([ADR|I,CNV||,KEY| 
LCFXINFXI 






|,*M5Njf>SNj j 

I.DFRINPFI 

|,I>IR||,SEQ||,SKP| 

IJCllNCil 






|,IN||,OUTJ 

|,NIS|SIS) 

|,NRM|AIX| 

|,NRS|RST| 

[,NSR|LSR| 

|,NLB|UBFJ)| 
IMAREA^ address] 
|,MLEN = number] 
[J>ASSWD = address] 
I.RMODE31 - f ALLIBUFFICBINONEJI 
|,SHRPOOL= {^number)] 
ISYKNQ** address] 
|,WAREA- address] 
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GENCB (Generate an Exit List at Execution Time) 



]tabel\ 


GENCB 


BLK-EXLST 
l,AM = VSAMI 
|,COPIES~ number] 
|,EODAD - (address],A\S\\X\)] 
(JRNAD - (a</</rexy|,A|N||,L|)| 
I,LENGTH = /i«mM 
|,LER AD - (address\,A\K]]M)\ 
I,LOC=fBELOVV|ANY) 
|,SYNAD » {address{ y A\S\m>] 
I,WAREA = address]" 



GENCB (Generate a Request Parameter List at Execution lime) 



{label] 


GENCB 


BLK-RPL 
|,ACB = address] 
I.AM-VSAMI 
(,AREA - address] 
|,AREALEN = number] 
|,ARG = address] 
|,COPIES = number] 
|,ECB = address] 
lKE\hEN = number] 






* lLESGTIf=numberf 
|,LOC=fBELOW|ANY)l 
{,M$GAREA = address] 
|,MSGLEN = number] 
I,NXTRPL = address] 
|,OPTCD = (|ADR|CNV|KEY| 

|,I)IR|SEQ|SKP| 

(,ARD|LRD| 

|,FWD|BWD| 

I,ASY|SYN| 

l,NSP|NUP|UPD| 

I.KEQ1KGE1 

|,FKS|GEN| 

|,LOC|MVE|)| 
]&ECLEW = number] 
[,TRANSID = number] 
i,WAREA = address] 



GET (Retrieve a Record) 



{label] 


GET 


RPL= address 
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GETIX (Retrieve an Index Record) 



[label] GETIX RPL = address 



MNTACQ (Mount Acquire) 



]labet[ MM ACQ RPL = address 



MODCB (Modify an Access Method Control Block) 



[label] 


MODCB 


ACB - address 

I,BSTRNO = number] 

|,BUF\D = number] 

|,BUFNI- number] 

|,BUFSP = number] 

|,CATALOG = {YES|NO}| 

1,CRA={SCRA|UCRA}| 

IDD\AME= ddname] 

],EXLST = address] 

|,M ACRF = (| ADR|[,CNV||,KEY| 

|,CFX|NFX| 

|,DDN|DSN| 

|,DFR|NDFI 

|,I)IR||,SEQ||,SKP| 

1,ICI|NCI1 






1,1N||,OUT| 
|,MS|SIS| 
|,NRM|AIX| 
|,NRS|RST| 
|,NSR|LSRJ 
| f NUB|UBFD| 
[,MAREA = address] 
|,MLEN- number] 
[ y PASS\VD = address] 






I.RMODE3I = f ALLIBUFFICBINONEU 
ISURPOOL* number] 
|,STRNO = number] 



MODCB (Modify an Exit List) 



[label] 


MODCB 


EXLST = address 
|,EODAD = (address[,A\K][X\)] 
IJRNAD = (address],A\N]lL])} 
|,LERAD - (a<tare*i,A|Nl|,LI)| 
l,SYNAD - (address],A\N][X\)] 
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MODCB (Modify a Request Parameter List) 



[label] 


MODCB 


RPL* address 
(,ACB = address] 
|,AREA =» address] 
[,AREALEN = number] 
|,ARG = address] 
|,ECB» address] 
|,KEYLEiN«*wm£<?ff 
[,MSGAREA - address] 
I.MSGLEN- number] 
I.NXTRPL- address] 
|,OPTCD = (|ADR|CNV|KEYl 

(,ARD|LRD| 

|,FWD|BWD| 

[,DIR|SEQ|SKP| 

|,ASY|SYN| 

|,NSP|NUP|UPD| 

(,KEQ|KGE| 

[,FKS|GEN| 

|,LOC|MVE|) 
|,RECLEN = number] 
|,TRANSID = number] 



MRKBFR (Write Buffer) 



MRKBFR 



MARK- {DINVALID|XINVAIJD|OUI |RLS} 

,RPL = address 



OPEN (Connect Program and Data) 



[label] 


OPEN 


(address],(options)]...) 
|,MODE={24|31}| 



POINT (Position for Access) 



[label] POINT RPL = address 



PUT (Store a Record) 



[label] 


PUT 


RPL = address 
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PUTIX (Store an Index Record) 



]label] 


PUTIX 


RPL = address 



RPL (Generate a Request Parameter List at Assembly Time) 



]label] 


RPL 


ACB = address 
|,AM = VSAM| 
|,AREA = address] 
],AREALEN = number] 
|,ARG = address] 
|,ECB = address] 
|,KEYLEN = number] 
|,MSG AREA = address] 
|,MSGLEN = number] 






|,NXTRPL- address] 
|,OPTCD - (|ADR|CNV|KEY| 

LDIR1SEQ1SKP1 

|,AR1)|LRD| 

|,FWI)|BWI)| 

|,ASY|SYN| 

|,NSP|NUP|UPD| 

|,KE£|KGE| 

j,FKS|GEN| 

|,N\VAITX|WAITX| 

|,LOC|MVE|)I 
] y REClE>i = number] 






|,TJRANSID - number] 



SCHBFR (Search Buffer) 



SCHBFR 



IBFRNO- number] 
,RPL = address 
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SHOWCB (Display Fields of an Access Method Control Block) 



[labeil 


SHOWCB 


ACBaddress 
,AREA » address 
.LENGTH ~ number 
I.OBJECT- (DATAIINDEX)l 


,HELDS - (|ACBLENH,AVSPAC|I,BFRFNDJ 
|,BSTRNO|f,BUFND||,BUFNI| 
[,BUFNO||,BUFRDS||,BUFSP| 
|,CINV|f,DDNAME||,ENDRBA| 
|,ERROR||,EXLST||,FS| 
(,HALCRBA|i,KEYLEN|[,LRECLI 
|,MAREA|f,MLENI|,NCISI 
|,NDELR||,NEXCP||,NEXT1 
|,NINSR||,NIXL|f,NLOGR| 
|,NRETR||,NSSS|I,NUIW| 
|,NUPDR|(,PASSVVDI|,RKP| 
|,SH RPOOL|[,STMST|(,Sl RMAXI 
|,STRNO||,UIWl) 



SHOWCB (Display Fields of an Exit List) 



\label[ 


SHOWCB 


AREA - address 
,EXLST - address 
.LENGTH = number 






,FTELDS - (|EOD AD||,EXLLF:XI|,JR\ADJ 

I,lf:radii,synadd 



SHOWCB (Display Fields of a Request Parameter List) 



\!abe/\ 


SHOWCB 


AREA = address 

JLENGTH* number 

,RPL = address 

,FIELDS - (|ACBH,AIXPC|I,AREA| 

I^\REALEN1|,ARGH,ECBII,FDBKJ 
(,FTNCD|[,KEYLENII,MSGAREA| 
[,MSGLEN||,NXTRPL||,RBA| 
|,RECLEN||,RPLLEN||,TRANSID| 
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TESTCB (Test a Field of an Access Method Control Block) 



[label] 


TESTCB 


ACB = address 
|,ERET- address] 
I,OBJECT= DATA|INDEX| 


,{ATRB = (|ESDS1|,KSDSH,LDSH,REPL| 






|,RRDS||,SPAN|[,SS\VDH,WCK|)| 






ATRB = IJNQ 






CATALOG = { YES|NO} | 






M ACRF - ((ADR||,AIX||,CFX||,CNV||,DDN| 






|,1)FR||,DIR||,DSN||,GSR]|,ICI| 






|,IN|[,KEY||,I-SRH,NCI|[,NDFJ 






|,NFX|I,NISH,NRM||,NRS||,NSR| 






|,NUB||,OUT||,RST||,SEQ]|,SIS| 






|,SKP||,UBF|)| 






OFLAGS = OPEN| 






OPENOBJ « PATH|BASE| AIX| 






ACBLEN = /ium6er| 






AVSPAC = number\ 






BSTRNO- number] 






BUFNI) = number] 






BUFNI= number] 






BUFNO - number] 






BUFSP = number] 






CINV = number] 






DDNAME = ddname] 






ENDRB A - number] 






ERROR - number] 
EXIST = address] 






FS= number] 
KEYLEN = number] 
LRECL = number] 
M AREA = address] 
MLEN ■ number] 
NCIS - number] 
NDELR = number] 
NEXCP = number] 
NEXT- number] 
NINSR- number] 
NIXL ■ number] 
KLOGR = number] 
NRETR = number] 
NSSS = number] 
NVPDR- number] 
VASS\VD = address] 
RKP- number] 
SHRPOOL- number] 
STMST« address] 
STRNO = number) 
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TESTCB (Test a Field of an Exit List) 



[label] 


TESTCB 


jEXLST 588 address 
|,ERET = address] 

,{EODAD * {0]([address]],A]X][,L])} ] 
JRNAD= [0|(fa^rejj|[,A|NII,L|)}| 

LERAD= {0](\address\lA\X\m)}\ 
SYNAD= {OKI^f/rejj||,A|NH,L|))} 
(,EXLLEN = number] 



TESTCB (Test a Field of a Request Parameter List) 



[label] 


TESTCB 


RPL = address 






|,ERET= address] 
,[ACB = address] 
AIXFLAG = AIXPKP| 
AIXPC - number] 
AREA = address] 
AREALEN = number] 
ARG = address] 
ECB = address] 
FDBK = number] 
FI'NCD = number] 
KEYLEN = number] 






, MSGAREA = a<tar<?j4 

MSGLVJX** number] 

XXTRVL = address] 

IO = COMPLETE| 

OPTCD = (J ADR|I,ARD|I,ASY||,BWDH,C W| 
I,DIR||,FKS||,F\VI)|f,GEN||,KEQ| 
|,KEY||,KGE|I,LOC||,LRl)||,\IVE| 
I,NSP|[,NUP|I,SEQH,SKP||,SYN| 
!,UPD|)I 

RBA = number] 

RECLEN = number] 

RPLLEN = number] 

TRANSID = number) 



VERIFY (Synchronize End of Data) 



[label] 


VERIFY 


RPL = address 
(.ACTION- REFRESH) 
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WRTBFR (Write Buffer) 



WRTBFR 



RPL = address 
,TYPE«{ALL|CHK|DRBA|DS|LRU(perce*0|TRN} 
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Appendix B. List, Execute, and Generate Forms of Macros 



BLDVRP, DLVRP, GENCB, MODCB, SHOWCB, and TESTCB macros build 
a parameter list describing in codes the actions indicated by the operands you 
specify and pass the list to VSAM to take the indicated action. The list, execute, 
and generate forms of BLDVRP, DLVRP, GENCB, MODCB, SHOVVCB, and 
TESTCB allow you to write reentrant programs, to share parameter lists, and to 
modify a parameter list before using it. 

Following is a brief description of the list, execute, and generate forms: 

• The list form is used to build the parameter list cither inline (referred to as a 
simple list) or in an area remote from the macro expansion (referred to as a 
remote list). Both the simple- and the remote-list forms allow you to build a 
single parameter list that can be shared. 

• The execute form is used to modify a parameter list and to pass it to VSAM 
for action. 

• The generate form is used to build the parameter list in a remote area and to 
pass it 1© VSAM for action. 

The list, execute, and generate forms of the BLDVRP, DLVRP, GENCB, 
MODCB, SHOWCB, and TESTCB macros have the same format as the 
standard forms, with the exception of: 

• An additional keyword, MF 

• Keywords that are required in the standard form may be optional in the list, 
execute, and generate forms or may not be allowed in the execute form. The 
meaning of the keywords, however, and the notation that may be used to 
express addresses, names, numbers, and option codes arc the same. 

The sections that follow describe the format of the MF keyword and the use of 
list, execute, and generate forms. They also indicate the optional and invalid 
operands. 
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List-Form Keyword 



The format of the MF keyword for the list form is: 

MF= {L\{L,address[Jabet[)} 

where: 

L 

specifies that this is the list form of the macro. 

address 

specifies the address of a remote area in which the parameter list is to be 
built. The area must begin on a fullword boundary. You can specify the 
address in register notation or as an expression valid for a relocatable 
A-type address constant or a direct or indirect S-type address constant. 

label 

is a unique name that is used in an EQU instruction in the expansion of 
the macro; label is equated to the length of the parameter list. You do not 
have to know the length of the parameter list if you code label; the 
expansion of the macro determines the amount of storage required. 

Because the MF = L expansion docs not include executable code, register 
notation and expressions that generate S-type address constants cannot be used. 

If you code MF ~ L, the parameter Hs£ is built inline, which means that the 
program is not reentrant if the parameter list is modified at execution. 

If you code MF = (L,address), the parameter list is built in the remote area 
specified, and the area must be large enough for the parameter list. 

The size, in fullwords, of a parameter list is: 

• For GENCB, 4, plus 3 times the number of ACB, EXLST, or RPL 
keywords specified (plus 1 for DDNAME, EODAD, JRNAD, LERAD, or 
SYNAD) 

• For MODCB, 3, plus 3 times the number of ACB, EXLST, or RPL 
keywords specified (plus 1 for DDNAME, EODAD, JRNAD, LERAD, or 
SYNAD) 

• For SHOWCB, 5, plus 2 times the number of fields specified in the FIELDS 
operand 

• For TESTCB, 8 (plus 1 for either DDNAME, STMST, EODAD, JRNAD, 
LERAD, or SYNAD) 

If you code MF = (L,address,Iabel), the parameter list is built in the remote area 
specified. The expansion of the macro equates label with the length of the 
parameter list. 
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Execute-Form Keyword 



The format of the MF keyword for the execute form is: 
MF '«■ (E,address) 

where: 

E 

specifies that this is the execute form of the macro. 

address 

is the address of the parameter list. 

The expansion of the execute form of the macro results in executable code that 
causes: 

1 . A parameter list to be modified if requested 

2. Control to be passed to a routine that satisfies the request 

You may not use the execute form to add an entry to a parameter list. If you try 
to add an entry, you will receive a return code of 8 in register 1 5. 



Generate-Form Keyword 



The format of the MF keyword for the generate form is: 
MF = {G,address\JabeT[) 

where: 

G 

specifies that this is the generate form of the macro. 

address 

specifics the address of a remote area in which the parameter list is to be 
built. The area must begin on a full word boundary. 

label 

is a unique name that is used in an EQU instruction in the expansion of 
the macro; label is equated to the length of the parameter list. You do not 
have to know the length of the parameter list if you code label; the 
expansion of the macro determines the amount of storage required. 

If you code MF = (G,address), the parameter list is built in the remote area 
specified. 

If you code MF = (G,address,label), the parameter list is built in the remote area 
specified. The expansion of the macro equates the length of the parameter list to 
label. 
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List, Execute and Generate Formats 



List Form of BLDVRP 



Note: If FIX is specified, DLVRP must be issued by the same task that issues 
BLDVRP. STRNO is optional in the list form of BLDVRP, but, if it is not 
specified, it must be specified in the execute form. 

The format of the list form of BLDVRP is: 



BLDVRP 



BUFFERS = (size(number)jize(nwnber)„...) 

,MF=L 

[,FIX - {BFR|IOB|(BFR,IOB))| 

\,KEYLEH = length\ 

|,RMODE31 = fALLIBUFFlCBI NONEI l 

[,SIIRPOOL={0|n}| 

l,iMODE={24|37}| 

[,STRNO = number] 
l,TYPE=f LSRl , DATA |IM)EXHGSR)i 



Execute Form of BLDVRP 



Note: The address is the address of the parameter list built by a list form of 
BLDVRP. If you use register notation, you may use register 1, and a register 
between 2 and t2. Register I is used to pass the parameter list to VSAM. 
BUFFHRS may not be specified in the execute form of BLDVRP, because this 
operand affects the length of the parameter list. 

The format of the execute form of BLDVRP is: 



BLDVRP 



M¥ = (E,address) 

IKKYLEX = length\ 

[,RMODE31 - fALLIBUFFlCBI NONEI l 

|,SHRPOOL = /M//nM 

I,MODE = {24|31}| 

j,STRNO = number] 

|,TYPE = f LSRl . DATA HNDEXllGSRM 



Note: If MODE = 31 was specified on the list form, MODE = 31 must be 
specified on the execute form. The same is true for MODE = 24. 
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Execute Form of DLVRP 



Note: There is no list form for DLVRP, because DLVRP works with 
BLDVRP: It uses the parameter list associated with BLDVRP. The address is 
the address of the parameter list built by a list form of BLDVRP. If you use 
register notation, use register 1 to pass the address of the parameter list to 
VSAM. 

If MODB = 31 in the BLDVRP macro, then MODE = 31 is required in the 
DLVRP macro. 

The format of the execute form of DLVRP is: 



DLVRP 



MF - (F,,address) 
|,SHRPOOL = /*um6er1 
|,MODE={24|31}| 
,TYPE={LSR|GSR} 



List Form of GENCB 



The format of the list form of GENCB is: 



[labell 


GENCB 


BLK- {ACB|EXLST|RPL} 
I.AM-VSAMI 
],COPlES = number] 

[keyword- {address\ncune\number\option} ,...| 

|, LENGTH = number] 

I.LOC = f BELOWI ANY11 

l,RMODE3I = f ALLlBUmnCBlNONEll 

,MF = {L\{Uaddres^labeH)} 

|,VV AREA = address] 



Execute Form of GENCB 



The format of the execute form of GENCB is: 



\labe1\ 


GENCB 


BLK= {ACB|EXLST|RPL} 
l,AM = VSAMI 
|,COPIES -/wm&erj 

[Jceyword- [address\name\number\option} ,...| 

|,LENGTH = number] 

l,LOC=fBELOW|ANY)l 

I.RMODE31 = f ALLIBUFFICBINONEH 


,MF = (E,address) 
\,W AREA** address] 
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Generate Form of GENCB 



The format of the generate form of the GENCB macro is: 



\label\ 


GENCB 


BLK = {ACB|EXLST|RPL} 
UM-VSAMI 
|,COPIES = /zw/tiM 

[^keyword— address\name\number\option} ,...) 

|,LENGTH = /zum6er| 

IXOC-fBELO\V|ANY)l 

(,RMODE31 - (ALLiBUFFlCBINONE)l 

,MF = (G,address[Jabel\) 

[,\VAREA = address] 



List Form of MODCB 



The format of the list form of MODCB is: 



[label\ 


MODCB 


{ ACB|EXLST|RPL{ = address 

^keyword- \address\name\number\option} ,... 

,MF = {L\{L,address\,label\)} 



Execute Form of MODCB 



Note: If the execute, form of MODCB is used and EXLST is used as a keyword 
to be processed, the block must be identified by ACB = . 

The format of the execute form of MODCB is: 



\label\ 


MODCB 


|{ACB|EXLST|RPL) = address] 

keyword = [address\ name\ number\ option] ,... 

,MF = {^address) 



Generate Form of MODCB 



The format of the generate form of MODCB is: 



\label\ 


MODCB 


(ACB|EXLST|RPL{ - address 

Jceyword** {address\name\number\option},... 

,MF - (G,address[,label\) 
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List Form of SHOWCB 



The format of the list form of SHOWCB is: 



]label] 


SHOWCB 


|{ACB|EXLST|RPL} - address] 

,AREA = address 

,FIELDS = (keyword[Jceyword,...\) 

,LENGTH = number 

,MF = iL\(L,address\,tabel\)} 

,OBJECT= fDATAIINDEXll 



Execute Form of SHOWCB 

The format of the execute form of SHOWCB is: 



\label\ 


SHOWCB 


|{ACB|EXLST|RPL} = address 
,AREA = address 
,MF '- (E,address) 
[,OBJECT = (DA TA|INDEX)| 



Generate Form of SHOWCB 

The format of the generate form of SHOWCB is: 



\label[ 


SHOWCB 


|{ ACB|EXLST|RPL] = address] 

,AREA = address 

^FIELDS = (keywora\,keyword,...]) 






,LENGTH = number 
,MF = (G,address\,Iabet\) 
|,OBJECT = fDATAIINDEXll 



List Form of TESTCB 



Note: If the execute form of TESTCB is used and EXLST is used as a keyword 
to be processed, the block must be identified by ACB = . 

The format of the list form of TESTCB is: 



[label] 


TESTCB 


|{ ACB|EXLST|RPL} = address] 
|,ERET = address] 

keyword '= {address\name\number\option} ,... 
,MF= [L\(Uaddress\,Iabel])} 
LOBJECT- f DATAIINDEXH 
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Execute Form of TESTCB 



Note: If the execute form of TESTCB is used and EXLST is used as a keyword 
to be processed, the block must be identified by ACB = . 

The format of the execute form of TESTCB is: 



\label\ 


TESTCB 


({ACB|EXLST|RI*L} = address] 
\,ERET = address] 

keyword- {address\name\nwnber\option} ,... 
,MF = (E,address) 
M)BJECT= fDATAIINDEXll 



Generate Form of TESTCB 



The format of the generate form of TESTCB is: 



[label] 


TESTCB 


I{ACB|EXLST|RPL) - address] 

|,ERET = address] 

keyword — { address\name \ nwnber\ option) ,... 

,MF - (G,address[,labei\) 

I.OBJECT- fDATAIINDEXH 



Use of List, Execute, and Generate Forms 



Figure 16 indicates which forms of GENCB, MODCB, SHOWCB, and 
TESTCB should be used in rccntrant/nonreentrant and shared/nonshared 
environments. 



Shared 



Reentrant 

MF = (L,address[JabeI\) 
MF = (E,address) 



Nonshared MF = (G,address[,label\) 

Figure 16. Reentrant Programming 



Nonreentrant 

MF=L 

MF = (E t address) 

Standard Form 



The figure shows that: 

• To share parameter lists in a reentrant program, the remote-list form should 
be used in conjunction with the execute form. 

• To share parameter lists in a nonreentrant program, the simple-list form 
should be used in conjunction with the execute form. 
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• If you do not intend to share parameter lists, the generate form should be 
used in reentrant programs and the standard form should be used for 
nonrecntrant programs. 



Examples of Generate, List, and Execute Forms in Reentrant Environments 

The examples that follow illustrate how the list, execute, and generate forms 
work. 



Example: Generate Form (Reentrant) 



In this example, the generate form of GENCB is used to create a default request 
parameter list (RPL) in a reentrant environment. 

Get length of the parameter list. 

Get storage for the area in which 
the parameter list is to be built. 

Save address of parameter- list 
area. 



LA 


10.LEN1 


GETMAIN 


JR,LV=(10) 


LR 


2,1 


GENCB 


BLK=RPL, 
MF=(G,(2),LEN1) 



The macro expansion equates LEN1 to the length of the parameter list, as 
follows: 

+LEN1 EQU 16 

The parameter list will be built in the area acquired by the GETMAIN macro 
^nd pointed to by register 2. This fast is used by VSAM to ^>uiid the RPL. 
VSAM returns the RPL address in register l and the RPL length in register 0. If 
the WAREA and LENGTH parameters are used, the RPL will be built at the 
VVAREA address. 



Example: Remote-List Form (Reentrant) 



In this example, the remote-list form of MODCB is used to build a parameter list 
that will later be used to modify the MACRF bits in the access method control 
block ANYACB. 

Get length of the parameter 
list. : 

Get storage for the area in 
which the parameter list is to 
be built. 

Save address of the 
parameter-list area. 



LA 


8,LEN2 


GETMAIN 


R,LV=(8) 


LR 


3,1 


MODCB 


ACB=ANYACB, 
MACRMF=(L,(3),LEN2) 



The macro expansion equates the length of the parameter list to LEN2, as 
follows: 

+LEN2 EQU 24 
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This parameter list is built in the remote area pointed to by register 3. The list 
will be used by VSAM to modify the ACB when an execute form of MODCB is 
issued (see next example). The list form only creates a parameter list; it does not 
modify the ACB. 



Example: Execute Form (Reentrant) 



In this example, the execute form of MODCB is used to modify the address of 
the access method control block and MAC RF codes in the parameter list created 
by the remote-list form of MODCB in the previous example. 

MODCB ACB=MYACB , MACRF=( ADR, SEQ, OUT) , MF=(E , ( 3) ) 

The parameter list pointed to by register 3 is changed so that the ACB and 
MACRF parameter values in the execute form override those in the list form. 
The access method control block, MYACB, is then modified to 
MACRF = ADR,SEQ,OUT). The access method control block at ANYACB is 
not changed by either of these examples. 
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Appendix C. Operand Notation 



Operands with GENCB, MODCB, SHOWCB, and TESTCB 

The addresses, names, numbers, and options required with operands in GENCB, 
MODCB, SIIOWCB, and TESTCB can be expressed in a variety of ways: 

• An absolute numeric expression, for example, STRNO = 3 and COPIES = 10. 

• A code or a list of codes separated by commas and enclosed in parentheses, for 
example, OPTCD= KEY or OPTCD = (KEY,DIR,IN). 

• A character string, for example, DDNAME= DATASET. 

• A register from 2 through 12 that contains an address or numeric value, for 

example, SYNAD = (3); equated labels can be used to designate a register, for 
example, SYNAD = (ERR), where the following equate statement has been 
included in the program: ERR EQU 3. 

• An expression of the form (S,scon), where scon is an expression valid for an 
S-type address constant, including the base-displacement form. The contents 
of the base register will be added to the displacement to obtain the value of 
the keyword. For example, if the value of the keyword being represented is a 
numeric value (that is, COPIES, LENGTH, RECLEN), the contents of the 
base register will be added to the displacement to determine the numeric 
value. If the value of the keyword being represented is an address constant 
(that is, WAREA, EXLST, EODAD, ACB), the contents of the base register 
will be added to the displacement to determine the value of the address 
constant. 

• An expression of the form (*,scon), where scon is an expression valid for an 
S-type address constant, including the base-displacement form; the address 
specified by scon is indirect, that is, it is the address of an area that contains 
the value of the keyword. The contents of the base register will be added to 
the -displacement to determine the address of the fullword of storage that 
contains the value of the keyword. 

If an indirect S-type address constant is used, the value it points to must meet 
the following criteria: 

— If it is a numeric quantity or an address, it must occupy a fullword of 
storage. 
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— If it is an alphameric character string, it must occupy two words of 
storage, be left aligned, and be filled on the right with blanks. 

• An expression valid for a relocatable A- type address constant, for example, 
AREA=MYAREA+4. 

The specified keyword determines the type of expressions that can be used. 
Additionally, register and S-type address constants cannot be used when MF= L 
is specified. 



The tables containing the individual macro operand notations have been deleted 
from this release. This information may be obtained from the individual macro 
descriptions shown in Chapter 2, "VSAM Macro Formats and Examples". 



1 82 MVS/XA VSAM Administration: Macro Instruction Reference 



Appendix D. Building Parameter Lists 



The standard forms of GENCB, MODCB, SHOWCB, and TESTCB build a 
parameter list, put its address in register 1, and pass control to a VSAM routine 
to generate, modify, display, or test an access method control block, exit list, or 
request parameter list. Other forms of the macros only build the parameter list 
(list forms) or only pass control to VSAM (execute forms). 

You can avoid using a macro to build the parameter list by building it yourself 
and issuing the execute form of the macro to pass control to VSAM. This 
chapter explains how to build the parameter lists for GENCB, MODCB, 
SHOWCB, and TESTCB. The rules for combinations of codes in a parameter 
list arc the same as the rules for combinations of operands in a macro. 

You can avoid issuing the execute form of the macro by coding the linkage 
instructions that pass control directly to the VSAM control block manipulation 
routine. Before passing control, you must build the parameter list yourself. 



The Format of the Parameter Lists 



A parameter list for GENCB, MODCB, SHOWCB, or TESTCB is a list of 
fullword addresses. The first address points to a header entry that identifies the 
type of request and type of control block and gives other general information 
about the request. Each of the rest of the addresses in the parameter list points 
to an element entry that identifies the information you want to generate, modify, 
display, or test. 

The fullwords in the parameter list must be contiguous, and the last one must 
have a 1 in its first bit. The header entry and each clement entry may be separate 
from each other. Figure 17 on page 184 gives the formats of the header and 
element entries for the four request types. 
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Generation 
GENCB 



Modification 
MODCB 



Display 
SHOWCB 







Header Entry 





GENBTC 

Control- 
block type 


GENFTC 

Function 
type 


GENCOP 

Number of copies 
of block 


4 


GENUSA (optional) 

Address of area provided 
for generation 


8 


GENUSL (optional) 
Length of area 


(reserved) 



Element Entry 






MODBTC 

Control- 
block type 


MODFTC 

Function 
type 


(reserved) 


4 


MODBLAD 

Address of control block 
to be modified 



12 



SHOWBTC 
(optional) 
Control- 
block type 


SHOWFTC 

Function 
type 


SHOWOBJ 

Object type 
(data or index) 


SHOWBtAD (optional) 

Address of control 
block to be displayed 


SHOWUSA 

Address of area provided 
for display 


SHOWUSL 

Length of area 


(reserved) 



ELEMKWTC 

Keyword 
type 


(reserved) 


Keyword value 


' (required for 
| some keywords)* 

L . ■ „ 




1 

1 

J 




ELEMKWTC 

Keyword 
type 


(reserved) 


Keyword value 


(required for 
1 some keywords)* 




1 

1 

i 




ELEMKWTC 

Keyword 
type 


(reserved) 



Test 
TESTCB 



12 



TESTBTC 
(optional) 
Control- 
block type 



TESTFTC 

Function 
type 



TESTOBJ 

Object type 
(data or index) 



TESTBLAD (optional) 
Address of control 
block to be tested 



TESTERET (optional) 

Address of error-analysis 
routine (ERET) 



(reserved) 






ELEMKWTC 

Keyword 
type 


(reserved) 


4 


Keyword value 


8 


(required for | 
some keywords)* i 

L J 



♦Second fullword required for 
keyword value of DDNAME, 
STMST, EODAD, JRNAD, 
LERAD, and SYNAD. 



Figure 17. Format of Header and Element Entries for GENCB, MODCB, SHOWCB, and TESTCB Parameter Lists 
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Building Header and Element Entries 



Five assembler macros are provided for building entries. 
IDAGENC, IDAMODC, IDASHOW, and 1DATEST help you build a header 
entry for generation, modification, display, or test. IDAELEM helps you build 
an element entry. 



\label\ 


IDAGENC 


|DSECT={YES|NO)| 


\label[ 


IDAMODC 


|DSECT={YES|NO)| 


[label\ 


IDASHOW 


|DSECT=(YES|NO)| 


\label\ 


IDATEST 


|DSECT={YES|NO}| 


\label\ 


IDAELEM 


(DSECT ={YES|NO}| 



DSECT ={YES|NO} 

Indicates whether a DSECT statement is to be generated. If you intend to 
build entries in a continuous area, you could have only the first of the 
macros generate a DSECT statement and use a single register to address the 
whole area. 

These macros generate labeled DS statements that give the layout of an entry and 
EQU statements that equate a label with a numeric code. You can symbolically 
encode an entry with a scries of move instructions. The macros arc 
self-documenting— inspect a listing of their expansions and you can sec which 
labels to code in your move instructions. (You can list the macros as they 
appear in the macro library.) 

To generate an exit list with LEkAD and SYNAD exits, you could code a 
GENCB of the standard form: 

GENCB BLK=EXLST, LERAD=(LOGERR, L) , SYNAD=PHYSERR 

The following example shows how to achieve the same effect by building the 
parameter list and entries yourself and issuing a GENCB of the execute form. 



LA 5,NTRYAREA 
USING 5,GENC 



Set up base register for 
the entries. 

GENC is the first label in 
the work area. 



Build the list of addresses that point to the entries 



ST 
LA 



ST 



5,PLIST 
6,GENLEN(,5) 

6,PLIST+4 



Address of the header 
entry. 

Address of the first 
element entry. GENLEN is 
equated to the length of 
a header element for 
generation. 
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LA 



6,ELEMLLEN(,6) 



ST 6,PLIST+8 
01 PLIST+S.X'SO' 
Build the header entry. 

MVI GENBTC.GENXLST 

MVI GENFTC.GENFTYP 

MVI GENCOP+l.X'Ol 1 



MVI ELEMKWTC+1, 
ELEMLEAD 

LA 6,L0GERR 



ST 6.ELEMPTR 

MVI ELEMXFLG, 

ELEMXL*ELEMXADR 



Build the second element entry. 



Address of the second 
element entry. ELEMLLEN 
is equated to the length 
of an element entry for 
an exit list. 



End-of-list indicator. 



Indicate the 
blocktype-exit list. 

Indicate the function 
type -generation. 

Indicate the number of 
copies of the exit list 
to be generated. 

Indicate the keyword type- 
LERAD. 

Address of the name of the 
logical error analysis 
module. 



Indicate the presence of 
an, address ELEMBTR and 
that the exit routine is 
to be loaded. 



LA 



5,ELEMLLEN(,5) 



MVI 


ELEMKWTC+1, 
ELEMSYAD 


LA 


6,PHYSERR 


ST 


6,ELEMPTR 


MVI 


ELEMXFLG, 
ELEMXADR 



Align the DSECT with the 
second element entry. 
ELEMLLEN is equated to the 
length of an element entry 
for an exit list. 

Indicate the keyword 
type-SYNAD. 

Address of the entry point 
of the physical error 
analysis routine. 



Indicate the presence of 
an address in ELEMPTR. 



Pass control to VSAM. 

GENCB MF=(E,PLIST) 
LTR 15,15 
BNZ CHECKO 



Generation successful? 
No. 
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CHECKO ABEND l.DUMP 



Register indicates the 
error. 



Physical error analysis exit routine. 
PHYSERR . . . 



Work areas and constants. 
LOGERR DC CLS'LEMOD' 



PLIST DC 



3F'0' 



Name of the 

logical error analysis 

module to be loaded. 

List of entry addresses. 
3 addresses are 
required: 1 for the header 
and 2 for the elements 
(1 for LERAD and 1 for 
SYNAD). 

Work area for header and 
element entries. The 
header for GENCB is 3 
fullwords, and so are 
the LERAD and SYNAD 
elements. 



DSECT with labels for the header and element entries. 



NTRYAREA DC 



9F'0' 



IDAGENC 



IDAELEM DSECT=NO 



Header entry. A DSECT 
statement is generated, 
and register 5 is used 
to address NTRYAREA 
with these labels. 

Element entry. Element 
labels are part of the 
same DSECT as the 
header labels. 



Passing Control Directly to VSAM 



You can avoid using the execute form of GENCB, MODCB, SHOWCB, and 
TESTCB by building your own linkage instructions. You first build a parameter 
list, as described in the previous section, and put its address in register 1. Then 
you pass control to VSAM using the following instructions: 



15,16 



15,256(,15) 



15,12(,15) 



BALR 14,15 



Put the address of the CVT 
into register 15. 

Put the address of the AMCBS 
control block into register 15. 

Put the address of the control 
block manipulation routine into 
register 15. 
Branch to the routine 



The BALR 14,15 instruction is used when the specific function (GENCB, 
MODCB, SHOWCB, or TESTCB) is not known, or when the control block 
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type (ACB, EXLST, or RPL) is not known. The user-built parameter list 
contains the function code and control block type code. 



Decimal 






Value of xx 


Function 


Control Block 


8 


GENCB 


ACB 


12 


GENCB 


RPL 


16 


GENCB 


EXLST 


20 


Reserved 




24 


iMODCB 


ACB 


28 


MODCB 


RPL 


32 


MODCB 


EXLST 


36 


Reserved 




40 


SHOWCB 


ACB 


44 


SIIOWCB 


RPL 


48 


SHOWCB 


EXLST 


52 


Reserved 




56 


TESTCB 


ACB 


60 


TESTCB 


RPL 


64 


TESTCB 


EXLST 


68 


Reserved 




72 


SIIOWCB or 


Block length 




TESTCB 


keywords only 


76» 


SIIOWCB 


RECLEN field 
of an RPL 


80» 


MODCB 


RECLEN field 
of an RPL 



Register 1 points to an RPL when xx is 76 or 80. 
for details. 



See the following section 



When VSAM returns to your program, register 15 contains a completion code. 
Register 15 contains a zero value if the task completed successfully. Otherwise, 
register 15 and register contain codes that identify the reason VSAM could not 
complete the task. 



Modifying and Displaying the RECLEN Field of an RPL Directly 



You can modify or display the RECLEN field (that is, the record length) of an 
RPL without issuing a SIIOWCB or MODCB macro, and without building a 
parameter list. 

To modify a RPL's RECLEN field, you first put the address of the RPL in 
register 1, and the value to be set in the RECLEN field in register 0. Next, you 
code the instructions that put the address of the VSAM control block 
manipulation routine into register 15, then branch to the routine: 
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L 15,16 Put the address of the CVT into 

register 15. 

L 15, 256 (,15) Put the address of the AMCBS 

control block into register 15. 

L 15,12(,15) Put the address of the control 

block manipulation routine 
into register 15. 

BAL 14,80(,15) Branch to the routine. 

When VSAM returns to your program, register 15 contains a completion code. 
Register 15 contains a zero value if the field was modified correctly. Otherwise, 
register 1 5 and register contain codes that identify the reason VSAM could not 
complete the task. 

To display the contents of a RPL's RliCLEN field, you first put the address of 
the RPL in register 1. Next, you code the instructions that put the address of the 
VSAM control block manipulation routine into register 15, and then branch to 
the routine: 

L 15,16 Put the address of the CVT into 

register 15. 

L 15, 256 (,15) Put the address of the AMCBS 

control block into register 15. 

L 15,12(,15) Put the address of the control 

block manipulation routine into 
register 15. 

BAL 14,76(,15) Branch to the routine. 

When VSAM returns to your program, register 15 contains a completion code. 
Register 15 contains a zero value if the field is displayed correctly, and register 
contains the value of the RPL's RFICLEN field. When register 15 is not zero, 
register 15 and register contain codes that identify the reason VSAM could not 
complete the task. 
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Glossary of Terms and Abbreviations 



The following terms arc defined as they are used in this 
book. If you do not find the term you are looking for, 
sec the index or the IBM Vocabulary for Data 
Processing, Telecommunications, and Office Systems, 
GC20-1699. 

ACB. (See access method control block.) 

access method control block. A control block that links 
an application program to VSAM or ACF/VTAM. 

access method services. A multifunction service 
program that is used to define VSAM data sets and 
allocate space for them, convert indcxcd-scqucntial data 
sets to key-scqucnccd data sets, modify data set 
attributes in the catalog, reorganize data sets, facilitate 
data portability between operating systems, create 
backup copies of data sets, help make inaccessible data 
sets accessible, list the records of data sets and catalogs, 
define and build alternate indexes, and convert OS 
CVOLs and VSAM catalogs to integrated catalog 
fariliiy catalogs. 

acquire. To allocate space on a staging drive and to 
stage data from an MSS cartridge to the staging drive. 

addressed-direct access. The retrieval or storage of a 
data record identified by its RBA, independent of the 
record's location relative to the previously retrieved or 
stored record. (See also keyed-direct access, addressed- 
sequential access, and keyed -sequential access.) 

addrcsscd-scqucntial address. The retrieval or storage of 
a data record in its entry sequence relative to the 
previously retrieved or stored record. (See also 
keyed-sequential access, addressed-direct access, and 
keyed -direct access.) 

alternate index. A collection of index entries organized 
by the alternate keys of its associated base data records. 
It provides an alternate means of locating records in the 
data component of a cluster on which the alternate 
index is based. 

alternate index cluster. The data and index components 
of an alternate index. 

alternate key. One or more consecutive characters 
taken from a data record and used to build an alternate 



index or to locate one or more base data records' via an 
alternate index. (See also generic key, key, and key 
field.) 

APF. (See authorized program facility.) 

application. As used in this publication, the use to 
which an access method is put or the end result that it 
serves; contrasted to the internal operation of the access 
method. 

authorized program facility. A facility that permits the 
identification of programs that arc authorized to use 
restricted functions. 

base cluster. A kcy-scqucnced or cntry-sequcnccd data 
set over which one or more alternate indexes are built. 

base RBA. The RBA stored in the header of an index 
record that is used to calculate the RBAs of data or 
index control intervals governed by the index record. 

catalog. (See master catalog and user catalog.) 

catalog recovery area. An cntry-scqucnccd file that 
exists on each volume owned by a recoverable catalog, 
including the catalog itself. The CRA contains records 
that arc duplicates of the catalog entries describing the 
volume and the files it contains. 

CBIC. Control blocks in common, a facility that allows 
a user to open a VSAM data set so the VSAM control 
blocks arc placed in the common service area (CSA) of 
the MVS operating system. litis provides the capability 
for multiple memory accesses to a single VSAM control 
structure for the same VSAM data set. 

chained RPL. (See RPL string.) 

CI. (See control interval.) 

CIDF. (See control interval definition field.) 

cluster. A named structure consisting of a group of 
related components (for example, a data component 
with its index component). A cluster may consist of a 
single component (See also base cluster and alternate 
index cluster.) 
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collating sequence. An ordering assigned to a set of 
items, such that any two sets in that assigned order can 
be collated. 

component. A named, cataloged collection of stored 
records. A component, the lowest member of the 
hierarchy of data structures that can be cataloged, 
contains no named subsets. 

control area. A group of control intervals used as a unit 
for formatting a data set before adding records to it. 
Also, in a key -sequenced data set, the set of control 
intervals pointed to by a sequence-set index record; used 
by VSAM for distributing free space and for placing a 
sequence-set index record adjacent to its data. 

control area split. The movement of the contents of 
some of the control intervals in a control area to a 
newly created control area, to facilitate the insertion or 
lengthening of a data record when there are no 
remaining free control intervals in the original control 
area. 

control interval. A fixed-length area of auxiliary storage 
space in which VSAM stores records. It is the unit of 
information transmitted to or from auxiliary storage by 
VSAM. 

control interval access. The retrieval or storage of the 
contents of a^coatrol interval. 

control interval definition field. In VSAM, the 4-byte 
control information field at the end of a control interval 
that gives the displacement from the beginning of the 
control interval to free space and the length of the free 
space. If the length is 0, the displacement is to the 
beginning of the control information. 

control interval split. The movement of some of the 
stored records in a control interval to a free control 
interval, to facilitate the insertion or lengthening of a 
record that won't fit in the original control interval. 

control volume. A volume that contains one or more 
indexes of the catalog. 

CRA. (See catalog recovery area.) 

cross memory. A synchronous method of 
communication between address spaces. 

CVOL. (See control volume.) 

DASD. (See direct access storage device.) 

data record. A collection of items of information from 
the standpoint of its use in an application, as a user 
supplies it to VSAM for storage. 



data set. The major unit of data storage and retrieval 
in the operating system, consisting of data in a 
prescribed arrangement and described by control 
information to which the system has access. As used in 
this publication, a collection of fixed- or variable-length 
records in auxiliary storage, arranged by VSAM in key 
sequence or in entry sequence. (See also key -sequenced 
data set and entry-sequenced data set) 

DD statement, data definition statement 

direct access. The retrieval or storage of data by a 
reference to its location in a data set rather than relative 
to the previously retrieved or stored data. (See also 
addressed -direct access and keyed-direct access.) 

direct access storage device. A device in which the 
access time is effectively independent of the location of 
the data. 

EBDIC Extended binary-coded decimal interchange 
code. A coded character set consisting of 8 -bit coded 
characters. 

entry sequence. The order in which data records are 
physically arranged (according to ascending RBA) in 
auxiliary storage, without respect to their contents. 
(Contrast with key sequence.) 

entry-scquenced data set. A data set whose records are 
loaded without respect to their contents, and whose 
RBAs cannot change. Records are retrieved and stored 
by addressed access, and new records are added at the 
end of the data set 

EOD. end of data 

EOKR. end-of-key range 

EO V. end of volume 

field. In a record or a control block, a specified area 
used for a particular category of data or control 
information. 

free control interval pointer list. In a sequence-set index 
record, a vertical pointer that gives the location of a free 
control interval in the control area governed by the 
record. 

free space. Space reserved within the control intervals 
of a key -sequenced data set for inserting new records 
into the data set in key sequence; also, whole control 
intervals reserved in a control area for the same 
purpose. 

GENDSP. An option of LOCATE to obtain the 
control interval number of the catalog record of each 
object 
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generation data group. A collection of data sets that are 
kept in chronological order; each data set is called a 
generation data set. 

generic key. A high-order portion of a key, containing 
characters that identify those records that are significant 
for a certain application. For example, it might be 
desirable to retrieve all records whose keys begin with 
the generic key AB, regardless of the full key values. 

global shared resources. An option for sharing I/O 
buffers, I/O-rclatcd control blocks, and channel 
programs among VSAM data sets in a resource pool 
that serves all address spaces in the system. 

GSR. (See global shared resources.) 

header, index record. In an index record, the 24-byte 
field at the beginning of the record that contains control 
information about the record. 

header entry. In a parameter list of GENCB, MODCB, 
SIIOWCB, or TFSTCB, the entry that identifies the type 
of request and control block and gives other general 
information about the request. 

horizontal pointer. In the header of an index record, the 
RBA of the index record in the same level as this one 
that contains keys next in ascending sequence after the 
keys in this one. 

index. As used in this publication, an ordered collection 
of pairs, each consisting of a key and a pointer, used by 
VSAM- 40 sequence tmd locate the Tceords of a 
key-sequenced data set. 

index level. A set of index records that order and give 
the location of all the control intervals in the next lower 
level or in the data set that it controls. 

index record. A collection of index entries that are 
retrieved and stored as a group. (Contrast to data 
record.) 

index record header. In an index record, the 24-bytc 
field at the beginning of the record that contains control 
information about the record. 

index replication. The use of an entire track of direct 
access storage to contain as many copies of a single 
index record as possible; reduces rotational delay. 

index set. The set of index levels above the sequence 
set. The index set and the sequence set together 
comprise the index. 

integrated catalog facility. The name of the catalog 
associated with the Data Facility Product program 
product. 



IOPID. I/O prevention identifier which is used to 
terminate I/O and prevent new I/O from being started. 

ISAM, indexed sequential access method 

ISAM interface. A set of routines that allow a 
processing program coded to use ISAM (indexed 
sequential access method) to gain access to a 
key-sequenced data set. 

JCL. (See job control language.) 

job catalog. A catalog made available for a job by 
means of the JOBCAT DD statement. 

job control language. A problem -oriented language 
designed to express statements in a job that arc used to 
identify the job or describe its requirements to an 
operating system. 

job step catalog. A catalog made available for a job by 
means of the STF.PCAT DD statement 

key. One or more characters within an item of data 
that arc used to identify it or control its use. As used in 
this publication, one or more consecutive characters 
taken from a data record, used to identify the record 
and establish its order with respect to other records. 
(See also key field and generic key.) 

key field. A field located in the same position in each 
record of a data set, whose contents arc used for the key 
of a record. 

key sequence. The collating sequence of data records, 
determined by the value of the key field in each of the 
data records. May be the same as, or different from, 
the entry sequence of the records. 

key-sequenced data set. A VSAM file (data set) whose 
records arc loaded in key sequence and controlled by an 
index. Records are retrieved and stored by keyed access 
or by addressed access, and new records are inserted in 
key sequence by means of distributed free space. 
Relative byte addresses of records can change because 
of control interval or control area splits. 

keyed-direct access. The retrieval or storage of a data 
record by use of cither an index that relates the record s 
key to its relative location in the data set or a relative 
record number, independent 01 the record's location 
relative to the previously retrieved or stored record. 
(See also addressed -direct access, keyed -sequential 
access, and addressed -sequential access.) ^ 

keyed-sequential access. The retrieval ohctorage of a 
data record in its key or relative record sequence relative 
to the previously retrieved or stored record, as defined 
by the sequence set of an index. (See also 
addressed -sequential access, keyed-direct access, and 
addressed -direct access.) 
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level number. For the index of a key-scquenced data 
set, a binary number in the header of an index record 
that indicates the index level to which the record 
belongs. 

linear data set (LDS). A named linear string of data, 
stored in such a way that it can be retrieved or updated 
in 4096 byte units. An LDS object is essentially a 
VSAM entry -sequenced data set that is processed as a 
control interval. I lowcvcr, unlike a control interval, an 
LDS contains data only, that is, it contains no record 
definition fields (RDFs) or control interval definition 
fields (CIDFs). 

local shared resources. An option for sharing I/O 
buffers, I, O-related control blocks, and channel 
programs among VSAM data sets in a resource pool 
that serves one partition or address space. 

LDS. (See linear data set) 

LSR. (See local shared resources.) 

master catalog. A catalog that contains extensive data 
set and volume information that VSAM requires to 
locate data sets, to allocate and deallocate storage space, 
to verify the authorization of a program or operator to 
gain access to a data set, and to accumulate usage 
statistics for data sets. 

operating system. Software that controls the execution 
of programs; an operating system may provide services 
such as resource allocation, scheduling, input/output 
control, and data management. 

password. A unique string of characters stored in a 
catalog that a program, a computer operator, or a 
terminal user must supply to meet security requirements 
before a program gains access to a data set 

path. A named, logical entity composed of one or more 
clusters (an alternate index and its base cluster, for 
example). 

physical record. A physical unit or recording on a 
medium. For example, the physical unit between 
address markers on a disk. 

pointer. An address or other indication of location. 
For example, an RBA is a pointer that gives the relative 
location of a data record or a control interval in the 
data set to which it belongs. 

prime index. The index component of a key-sequenced 
data set that has one or more alternate indexes. (See 
also index and alternate index.) 

prime key. (See key.) 

QSAM. (See queued sequential access method.) 



queued sequential access method. An extended version 
of the basic sequential access method (BSAM). When 
this method is used, a queue is formed of input data 
blocks that are awaiting processing or output data 
blocks that have been processed and are awaiting 
transfer to auxiliary storage or to an output device. 

RACF. Resource Access Control Facility. 

random access. (See direct access.) 

RBA. Relative byte address. The displacement 
(expressed as a fuilword binary integer) of a data record 
or a control interval from the beginning of the data set 
to which it belongs; independent of the manner in which 
the data set is stored. 

RDF. (See record definition field.) 

record. (See index record, data record.) 

record definition field. A field stored as part of a stored 
record segment; it contains the control information 
required to manage stored record segments within a 
control interval. 

relative byte address. (See RBA.) 

relative record data set. A data set whose records are 
loaded into fixed-length slots. 

relative record number. A number that identifies not 
only the slot, or data space, in a relative record data set 
but also the record occupying the slot. Used as the key 
for keyed access to a relative record data set. 

replication. (See index replication.) 

request parameter list. A control block that contains 
the information needed to process an IO request 

resource pool, VSAM. (See VSAM resource pool.) 

reusable data set. A VSAM data set that can be reused 
as a work file, regardless of its old contents. Must not 
be a base cluster. 

RI'L. (See request parameter list.) 

RPL string. A set of chained RPLs (the set may 
contain one or more RPLs) used to gain access to a 
VSAM data set by action macros (GET, PUT, etc). 
Two or more RPL strings may be used for concurrent 
direct or sequential requests made from a processing 
program or its subtasks. 

SAM. (See sequential access method.) 

security. (See data security.) 



194 MVS/XA VSAM Administration: Macro Instruction Reference 



sequence checking. The process of verifying the order 
of a set of records relative to some field's collating 
sequence. 

sequence set. The lowest level of the index of a 
key-sequenced data set; it gives the locations of the 
control intervals in the data set and orders them by the 
key sequence of the data records they contain. The 
sequence set and the index set together comprise the 
index. 

sequential access. The retrieval or storage of a data 
record in cither its entry sequence, its key sequence, or 
its relative record number sequence, relative to the 
previously retrieved or stored record. (See also 
addressed -sequential access and keyed-sequential 
access.) 

sequential access method. An access method for storing 
or retrieving data blocks in a continuous sequence, using 
cither a sequential access or a direct access device. 

shared resources. A set of functions that permit the 
sharing of a pool of I O-relatcd control blocks, channel 
programs, and buffers among several VSAM data sets 
open at the same time. 

skip-sequential access. Keyed-sequential retrieval or 
storage of records here and there throughout a data set, 
skipping automatically to the desired record or collating 
position for insertion: VSAM scans the sequence set to 
find a record or a collating position. Valid for 
processing in ascending sequences only. 

slot. For a relative record data set, the data area 
addressed by a relative record number which may 
contain a record or be empty. 

spanned record. A logical record whose length exceeds 
control interval length, and as a result, crosses, or spans, 
one or more control interval boundaries within a single 
control area. 

SRB. Service request block. A system control block 
used for dispatching tasks. 

step catalog. A catalog made available for a step by 
means of the STEPCAT DD statement. 

terminal monitor program. In TSO, a program that 
accepts and interprets commands from the terminal, and 
causes the appropriate command processors to be 
scheduled and executed. 

time sharing option. An optional configuration of the 
operating system that provides conversational time 
sharing from remote stations. 

TMP. (See terminal monitor program.) 



transaction ID. A number associated with each of 
several request parameter lists that define requests 
belonging to the same data transaction. 

TSO. (See time sharing option.) 

update number. For a spanned record, a binary 
number in the second RDF of a record segment that 
indicates how many times the segments of a spanned 
record should be equal. An inequality indicates a 
possible error. 

upgrade set. All the alternate indexes that VSAM has 
been instructed to update whenever there is a change to 
the data component of the base cluster. 

user buffering. The use of a work area in the processing 
program's address space for an I/O buffer; VSAM 
transmits the contents of a control interval between the 
work area and direct access storage without 
intermediary buffering. 

user catalog. An optional catalog used in the same way 
as the master catalog and pointed to by the master 
catalog. It also lessens the contention for the master 
catalog and facilitates volume portability. 

vertical pointer. A pointer in an index record of a given 
level that gives the location of an index record in the 
next lower level or the location of a control interval in 
the data set controlled by the index. 

virtual storage access method. An access method for 
direct or sequential processing of fixed and 
variable-length records on direct access devices. The 
records in a VSAM data set or file can be organized in 
logical sequence by a key field (key sequence), in the 
physical sequence in which they arc written on the data 
set or file (entry sequence), or by relative record 
number. 

virtual telecommunications access method. A set of 
programs that control communication between terminals 
and application programs running under VSE, OS VS1, 
and OSVS2. 

VSAM. (See virtual storage access method.) 

VSAM resource pool. A virtual storage area that is 
used to share I/O buffers, I/O-rclatcd control blocks, 
and channel programs among VSAM data sets. A 
resource pool is local or global; it serves tasks in one 
partition or address space or tasks in all address spaces 
in the system. 



VSAM shared information, 
cross-system sharing. 



Blocks that are used for 



VSI. (See VSAM shared information.) 
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I VTAM. (See virtual telecommunications access 
| method.) 
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control block manipulation macro 

return codes and reason codes 10 
control information 

parameter lists of GENCB, MODCB, SIIOWCB, 
and TESTCB macros 
address list 1 83 
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element entry 183 
header entry 183 
COPIES parameter 

in GENCB macro 71, 77, 81 
CRA parameter 

in ACB macro 36 
in GENCB macro 72 
in TESTCB macro 147 



E 



D 



48 



14* 



DATA option 

BLDVRP macro 
data set attributes 

testing in TESTCB macro example 
DDN subparametcr 

in MACRF parameter of the ACB macro 
DDN AM E parameter 

in ACB macro 37 

in FIELDS parameter 135 

in GENCB macro 72 
deferring write requests 3 
deleting a record 

addressed -sequential deletion 64 

ERASE macro 63 

key-direct deletion 63 
DFR subparamcter 

in MACRF parameter of the ACB macro 
DIN VALID subparamcter 

in MRKBFR macro 106 
DIR subparamcter 

in MACRF parameter of the ACB macro 

in OPrCD parameter of RPL macro 1 28 
direct processing 

reason code positioning stale 25 
disconnecting your program 

CLOSE macro 55 
DLVRP macro 

example 60 

execute form 175 

format 59 

return codes 31 

summary 160 
DRBA subparamcter 

in WRTBFR macro 157 
DS subparamcter 

in WRTBFR macro 157 
DSN subparametcr 

in MACRF parameter of the ACB macro 
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38 



38 



38 



ECB parameter 

in FIELDS parameter 142 

in GENCB macro 82 

in RPL macro 127 
ECB subparamcter 

CNVI AD macro 58 

MRKBFR macro 106 

SCHBFR macro 132 
element entry 

in parameter lists of GENCB, MODCB, SHOWCB, 
and TESTCB macros 183 
coding example 185 
illustration 185 
ellipses, in notation convention vii 
end-of-volume 

return codes 31 
ENDRBA parameter 

in FIELDS parameter 136 
ENDREQ macro 

example 61 

format 61 

terminating a request 
summary 1 60 

used with WRTBFR macro 1 56 
entry 

element, in parameter lists of GENCB, MODCB, 
SHOWCB, and TESTCB macros 1 83 

header, in parameter lists of GENCB, MODCB, 
SHOWCB, and TESTCB macros 1 83 
entry ^sequenced data set 

used in ACQ RANGE macro 44 
EODAD parameter 

in EXLST macro 66 

in GENCB macro 76 

in SHOWCB macro 139 

in TESTCB macro 150 
ERASE macro 

deleting a record 
summary 160 

format 63 
ERASE processing 63 
ERET parameter 

in TESTCB macro 146, 150, 152 
error field of the ACB 

reason codes from OPEN macro 2 
ERROR parameter 

in FIELDS parameter 135 
ESDS parameter 

in TESTCB macro 146 
event control block 

used in ACQ RANGE macro 45 
example 

addition of records, PUT macro 1 19 

addressed -sequential deletion, ERASE macro 64 

addressed -sequential retrieval, GET macro 89 

addressed-sequential update, PUT macro 1 23 
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check return code after asynchronous request, 

CHECK macro 51 
checking return code after synchronous request, 

CHECK macro 52 
close data set with parameter list above 1 6M, 

CLOSE macro 56 
connect LSR pool and run in 31 -bit addressing 

mode, ACB macro 43 
delete LSR pool, DLVRP macro 60 
display an ACB, SI IOWCB macro 1 37 
display an exit list address in the ACB, SI IOWCB 

macro 1 38 
display exit list length, SI IOWCB macro 140 
display physical error message, SHOWCB 

macro 144 
generate an access method control block, GENCB 

macro 75 
generate an exit list, GENCB macro 78 
generate an RPL at assembly time, RPL 

macro 131 
generate request parameter list, GENCB macro 85 
identify data set, ACB macro 42 
identify exit routines, EXLST macro 67 
keyed -direct deletion, ERASE macro 63 
keyed-direct insertion, PUT macro 118 
keyed-direct update, PUT macro 121 
keyed-sequential insertion, PUT macro 111, 115 
keyed-sequential retrieval (backward), GET 

macro 87 
keyed-seqecrrtiaf retrieval, GET macro- 86* 
keyed-sequential update, PUT macro 1 20 
loading a relative record data set, PUT macro 113 
marking records inactive, PUT macro 124 
modify a request parameter list, MODCB 

macro 105 
modify an exit list, MODCB macro 103 
modify name of exit list in ACB, MODCB 

macro 101 
obtain LSR above 16M, BLDVRP macro 49 
obtaining resource pool above 16M, BLDVRP 

macro 49 
open macro with parameter list above 16M, OPEN 

macro 108 
open two data sets, OPEN macro 108 
overlay processing, CHECK macro 52 
position, POINT macro 109 
recording RBAs when loading, PUT macro 112 
release positioning, ENDREQ macro 61 
request separate data and index pools, BLDVRP 

macro 50 
request separate data/index resource pools, 

BLDVRP macro 50 
retrieving a keyed-direct record, GET macro 92 
retrieving a relative record sequentially, GET 

macro 91 
retrieving an addressed -direct record, GET 

macro 93 
retrieving direct to sequential record, GET 

macro 94 
ski -sequential retrieval, GET macro 87 
skip-sequential insertion, PUT macro 116 
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suspend many record request, CHECK macro 53 

test a request parameter list, TESTCB macro 154 

test for data set attributes, TESTCB macro 148 

use a branch table, TESTCB macro 151 
example of generate, list, execute forms in reentrant 
environment 179 
execute form 

BLDVRP macro 

DLVRP macro 

GENCB macro 

MODCB macro 

SHOWCB macro 

TESTCB macro 

use of 1 78 
execute-form keyword 
execution time 

generate a request parameter list, summary 162 

generate an ACB 69 

generate an access method control block 161 

generate an exit list, summary 1 62 

generate exit list 76 

generate request parameter list 80 
exit list 

address displayed in SHOWCB macro 
example 1 38 

fields displayed in SHOWCB macro 139 

generating at execution time 76 

generating in EXLST macro 66 

length displayed in SHOWCB macro example 140 
EXLLEN parameter 

in SHOWCB macro 139 

in TESTCB macro 151 
EXLST macro 

example 67 

format 66 

generate exit list at assembly time 
summary 161 
EXLST parameter 

in ACB macro 37 

in FIELDS parameter 135 

in GENCB macro 72 

in MODCB macro 102 

in SHOWCB macro 139 

in TESTCB macro 150 







FDBK parameter 

in FIELDS parameter 142 
feedback word in the RPL 13 
FIELDS parameter 

in SHOWCB macro 134, 139, 142 
FIX parameter 

BLDVRP macro 46 
FKS subparamcter 

in OPTCD parameter of RPL macro 130 
format 

ACB macro 34 
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ACQRANGE macro 44 
BLDVRP macro 46 
CHECK macro 51 
CLOSE macro 55 
CNVTAD macro 57 
DLVRP macro 59 
ENDREQ macro 61 
ERASE macro 63 
execute form 

of BLDVRP macro 174 

of DLVRP macro 175 
EXLST macro 66 
GENCB macro 69 
G ET macro 86 
GETIX macro 97 
list form 

of BLDVRP macro 174 
MNTACQ macro 98 
MODCB macro 100 
MRKBFR macro 106 
OPEN macro 107 

parameter lists of GENCB, MODCB, SMOWCB, 
and TESTCB macros 

address list 185 

clement entry 185 

header entry 185 
PO I NT-macro 109 
PUT macro 1 1 1 
PLT IX macro 125 
RPL macro 126 
SCI I BFR macro 132 
SMOWCB macro 133 
TESTCB macro 145,150 
VERITY macro 155 
VV RIB PR macro 156 
format of the parameter lists 1 83 
ES parameter 

in FIELDS parameter 136 
FTNCD parameter 

in FIELDS parameter 142 
in TESTCB macro 153 
FVVD subparameter 

in OPTCD parameter of RPL macro 129 



GENCB macro 

execute form 175 

with parameter lists built by user 183, 185 
format 69 
generate a request parameter list at execution time 

summary 162 
generate an access method* control block at 
execution time 
summary 161 



generate ah exit list at execution time 
summary 1 62 

generate form 176 

reentrant example 1 79 

generating a request parameter list 80 

generating a request parameter list example 85 

generating an access method control block 69 

generating an access method control block 
example 75 

generating an exit list 76 

generating an exit list example 78 

inconsistent operand error 3 

linking to VSAM directly 187 

list form 175 

operand notation 181 

reason codes 10 

return codes 10 
generate form 

GENCB macro 176 

MODCB macro 176 

SMOWCB macro 177 

TESTCB macro 178 

use of 178 
gencratc-form keyword 173 
generating a request parameter list 

GENCB macro 80 

RPL macro 126 
generating an access method control block (GENCB 

macro) 69 
generating an exit list 

at assembly time 66 

GENCB macro 76 
G ET macro 

format 06 

retrieving a direct to sequential record example 94 

retrieving a keyed-direct record 92 

retrieving a keyed -sequential record (backward) 
example 

backward 87 

retrieving a record 
summary 1 62 

retrieving a relative record example 91 

retrieving a skip-sequential record, example 87 

retrieving an addressed -direct record example 93 

retrieving an addrcsscd-scqucntial record 
example 89 

retrieving keyed -sequential record example 
forward 86 
GETIX macro 

format 97 

retrieving an index record 
summary 163 
GSR option 

BLDVRP macro 48 

in MACRF parameter of the ACB macro 39 
GSR subparameter 

DLVRP macro 59 
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HALCRBA parameter 

in FIELDS parameter 
header entry 

in parameter lists of GENCB, MODCB, SHOWCB, 
and TESTCB macros 
coding example 185 
illustration 18S 
using macros to build 18S 
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ICI subparameter 

in MACRF parameter of the ACB macro 
IDAELEM macro 185 
IDAGENCmacro 185 
I DA. MO DC macro 185 
I DAS I IOW macro 185 
IDATESTmacro 185 
IN subparameter 

in MACRF parameter of the ACB macro 
index 

retrieval (GETIX macro) 97 

storing. (PUTIX macroV 1 25 
INDEX option 

BLDVRP macro 48 
indirect address for S-lype address constant 33 
indirect S-lype address constant 69 
inserting records 

keyed-direct 1 1 8 

keyed -sequential 111, 115 

skip sequential 116 
IO parameter 

in TESTCB macro 153 
IOP1D parameter 

in EXLST macro 66 
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38 







JRNAD parameter 

in EXLST macro 67 
in GENCB macro 77 
in SHOWCB macro 140 
in TESTCB macro- 150 



KEQ subparameter 

in OPTCD parameter of RPL macro 
KEY subparameter 

in MACRF parameter of the ACB macro 38 

in OPrCD parameter of RPL macro 1 28 
key-direct deletion 

example 63 
kcy-scquenced data set 

used in ACQRANGE macro 44 
KEYLEN parameter 

BLDVRP macro 47 

in FIELDS parameter 136, 143 

in GENCB macro 82 

in RPL macro 127 
keywords 

execute form 1 73 

generate form 1 73 

list form 1 72 
KGE subparameter 

in OPTCD parameter of RPL macro 
KSDS parameter 

in TESTCB macro 146 



130 



L 



146 



155 
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LDS parameter 

in TESTCB macro 
LENGTH parameter 

in GENCB macro 72, 77, 82 

in SHOWCB macro 133, 139, 141 
LERAD parameter 

in EXLST macro 67 

in GENCB macro 77 

in SHOWCB macro 140 

in TESTCB macro 150 
linear data set 

error in VERIFY macro 

logical error reason codes 
linking to VSAM directly 187 
list form 

BLDVRP macro 

GENCB macro 

MODCB macro 

SHOWCB macro 

TESTCB macro 

use of 178 
list-form keyword 172 
list, execute, generate formats 1 74 
list, execute, generate forms of macros 171 
list, parameter 

of GENCB, MODCB, SHOWCB, and TESTCB 
macros 183 
LOC parameter 

in GENCB macro 72, 77, 82 
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removal from the BLDVRP macro 47 
LOC subparameter 

in OPTCD parameter of RPL macro 130 
local shared resources 

ACB example 43 
locate mode 

with control interval access 
with shared resources 132 
lower case, in notation convention vii 
l.RD subparameter 

in OPTCD parameter of RPL macro 129 
LRECL parameter 

in FIELDS parameter 136 
LRU subparameter 

in WRTBFR macro 157 
LSR option 

BLDVRP macro 48 

DLVRP macro 59 

in M ACRF parameter of the ACB macro 39 
LSR pool 

example in BLDVRP macro 50 



M 



MACRF parameter 

in ACB macro 37 

in GENCB macro 72 

in TESTCB macro 147 
macro instruction return codes and reason codes 1 
macros 

descriptions 1 

summary of 159 
MA RE A parameter 

in ACB macro 40 

in FIELDS parameter 135 

in GENCB macro 73 
MARK parameter 

in MRKBFR macro 106 
marking records inactive 1 24 
message area 

header information 8 

message list 9 

OPEN/CLOSE 7 

provided by VSAM 7 
ML EN parameter 

in ACB macro 40 

in FIELDS parameter 135 

in GENCB macro 73 
MNTACQ macro 

format 98 

summary 163 
MODCB macro 

example 101 

execute form 176 

reentrant example 180 

with parameter lists built by user 183 

format 100 

generate form 176 



linking to VSAM directly 187 

list form 176 

modify a request parameter list example 105 

modify an exit list example 103 

modifying a request parameter list 104 

summary 164 
modifying an ACB 100 

summary 1 63 
modifying an exit list 
format 102 
summary 163 
operand notation 181 
reason codes 10 
remote-list form 

reentrant example 179 
return codes 10 
MODE option 

BLDVRP macro 48 
MODE parameter 
DLVRP macro 59 
in CLOSE macro 55 
in OPEN macro 107 
modifying and displaying the RECLEN field of an RPL 

dirccdy 188 
move mode of control interval access 

with shared resources 132 
MRKBFR macro 
format 106 
invalidating a buffer 
parameters for 106 
reason codes 106 
summary 164 
MSGAREA parameter 

in FIELDSjjaramctcr 143 
in GENCB macro 82 
in RPL macro 127 
MSGLEN parameter 

in FIELDS parameter 143 
>*in GENCB macro 82 
in RPL macro 127 
MVE subparameter 

in OPTCD parameter of RPL macro 130 
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NCI subparameter 

in MACRF parameter of the ACB macro 38 
NCIS parameter 

in FIELDS parameter 136 
NDELR parameter 

in FIELDS parameter 136 
NDF subparameter 

in MACRF parameter of the ACB macro 38 
NEXCP parameter 

in FIELDS parameter 136 
NEXT parameter 

in FIELDS parameter 136 
NFX subparameter 
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in MACRF parameter of the ACB macro 38 
NINSR parameter 

in F I E L DS parameter 1 36 
NIS subparamcter 

in MACRF parameter of the ACB macro 39 
NFXL parameter 

in FIELDS parameter 136 
NLOGR parameter 

in F I E 1 . DS parameter 1 36 
NO subparamcter, in CATALOG parameter 

in ACB macro 36 

in GENCB macro 71 

in TESTCB macro 147 

restriction 36, 71 
NRETR parameter 

in FIELDS parameter 136 
NRM option 

in MACRF parameter of the ACB macro 39 
NRS option 

in MACRF parameter of the ACB macro 39 
NSP subparamcter 

in OFrCD parameter of RPL macro 129 
NSR option 

in MACRF parameter of the ACB macro 39 
NSSS parameter 

in FIELDS parameter 136 
NUB option 

in MACRF parameter of the ACB macro 
NL'IW parameter 

in FIELDS parameter 137 
N U P suhparameter 

in OPICD parameter of RPL macro 1 29 
NUPDR parameter 

in FIELDS parameter 137 
NWAITX subparamcter 

in OPTCD parameter of RPL macro 130 
NXTRPL parameter 

in FIELDS parameter 143 

in GENCB macro 83 

in RPL macro 128 



39 



o 



OBJECr parameter 

inSIIOWCBmacro 134 

in TESTCB macro 146 
OF LAGS parameter 

in TESTCB macro 147 
OPEN macro 

connecting program and data 
summary 164 

format 107 

open two data sets example 108 

parameter list above 16M example 108 

reason codes 2 

use of SHOWCB macro 2 
use of VE RI FY command 2 

return codes 1 



shared resources 
reason codes 3 
OPEN/CLOSE message area for multiple 

reason/warning messages 7 
opening a data set 

for processing 107 
OPENOBJ parameter 

in TESTCB macro 148 
operand notation 

GENCB 181 

MODCB 181 

SHOWCB 181 

TESTCB 181 
operands 

optional 174 

required 1 74 
operands with GENCB, MODCB, SIIOWCB, 
TESTCB 181 
OPTCD parameter 

in GENCB macro 83 

in RPL macro 128 

in TESTCB macro 153 
OPrCD subparamcter 

ACQ RANG E macro 44 

GETIX macro 97 

in RPL macro 130 

MNTACQ macro 98 

PUTIX macro 125 

SCII BFR macro 132 
optional operands 174 
or sign, ia notation convention vil 
OUT subparamcter 

in MACRF parameter of the ACB macro 39 

in MRKBFR macro 106 



parameter list 

of GENCB, MODCB, SHOWCB, and TESTCB 
macros 183 
passing control directly to VSAM 187 
PASS WD parameter 

in ACB macro 40 

in FIELDS parameter 135 

in GENCB macro 73 
physical error analysis 

with control interval access 26 
physical error message 

displayed in SIIOWCB macro example 144 

format 30 

RBA field 26 
POINT macro 

format 109 

position example 109 

positioning for access 
summary 164 
positioning 

following logical errors 24 
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of reason codes 25 

positioning for access (POINT macro) 109 

PUT macro 

addressed -sequential update example 123 
format 1 1 1 

keyed -direct insertion example 1 18 
keyed-direct update example 121 
keyed -sequential insertion example 111, 115 
keyed -sequential update example 120 
loading a relative record data set 113 
marking records inactive example 124 
recording RBAs when loading example 1 12 
skip-sequential insertion example 116 
storing a record 
summary 1 64 

PUTIX macro 
format 1 25 
storing an index record 
summary 1 65 



R 



RBA field 

in physical error message 26 
RBA parameter 

in FIELDS parameter 143 
RBA values 

CNVTAD macro 58 

passed to M NT ACQ macro 58 
reason codes 

from OPEN macro 2 
uscoTSllQWCB 2 

from request macros (GET, PUT, etc.) 

physical errors, control interval access 26 

in control block manipulation macros 10 

in GENCB macro 10 

in MODCB macro 10 

in SI IOWCB macro 10 

in TESTCB macro 10 

logical errors 17 

physical errors 26 

positioning state 25 

request parameter list feedback area 1 3, 1 5 

shared resources from OPEN macro 3 

successful request 15 

use of VERIFY command in OPEN macro 2 
RECLEN field (record length) of an RPL 

modifying and displaying 188 
RECLEN parameter 

in FIELDS parameter 143 

in GENCB macro 83 

in RPL macro 130 
record 

retrieval (GET macro) 86 
record length (RECLEN field) of an RPL 

modifying and displaying 1 88 
record management 

return codes and reason codes 13 



reentrant program 33 
register notation 33, 69 
relative record data set 

used in ACQ RANGE macro 44 
relative record number 

used as a key 91 
releasing exclusive or shared control 

MRKBFR macro 106 
RE PL parameter 

in TESTCB macro 147 
request macros 

CHECK 51 

ENDREQ 61 

ERASE 63 

GET 86 

physical reason codes from 26 

POINT 109 

PUT 111 
request parameter list 

chaining 81, 126 

chaining example 84 

chaining in G ET macro 96 

chaining not allowed 

with SCI I BFR macro 132 
with WRTBFR macro 1 56 

changing 104 

component codes from component code field 1 4 

displaying fields in SI IOWCB macro 141 

generating at assembly time 

generating at execution time 80 

generating with GENCB macro example 85 

modifying 104 

reason codes from feedback area 1 5 

testing in TESTCB macro 152 

testing in TESTCB macro example 1 54 

with the GENCB macro 81 

with the RPL macro 126 
required operands 174 
resource sharing ? \ 
retrieving a record 

for deletion 64 
retrieving an index record 1 3 
return codes 

checking, example 51 

from asynchronous request 14 

from BLDVRP macro 30 

from CLOSE macro 6 

from DLVRP macro 31 

from end-of-volume 31 

from macros used to share resources 30 

from OPEN macro 1 

from RPL 13 

in control block manipulation macros 10 

in GENCB macro 10 

in MODCB macro 10 

in SI10WCB macro 10 

in TESTCB macro 10 

synchronous request 14 
return codes and reason codes from OPEN 1 
reusable data set 

specifying in ACB macro processing). 39 
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RKP parameter 

in FIELDS parameter 137 
RLS subparameter 

in MRKBFR macro 106 
RMODE31 parameter 

example in B L D VRP macro 49 

example in the GENCB macro 75 

in ACB macro 40, 43 

in BLDVRP macro 47 

in OPEN macro 107 

in the GENCB macro 73 

in the MOOCB macro 100 
RPL component code 13 
RPL condition code 13, 15 
RPL feedback area 13 
RPL feedback word 13 
RPL macro 

example 131 

format 1 26 

generate a request parameter list at assembly time 
summary 1 65 
RPL operand 

RECLEN field (record length) 
modifying and displaying 1 88 
RPL parameter 

in ACQ RANGE macro 44 

in BLK parameter in GENCB macro 81 

in CHECK macro 51 

in CNVTAD macro 57 

in ENDREQ macro 61 

in ERASE, macro 63, 

in GET macro 86 

in GETIX macro 97 

in MNTACQ macro 98 

in MODCB macro 104 

in MRKBFR macro 106 

in POINT macro 109 

in PUT macro 1 1 1 

in PUT1X macro 125 

in SCHBFR macro 132 
141 
152 
155 

156 
98 



n SHOVVCB macro 
n TESTCB macro 
n VERIFY macro 
n WRTBFR macro 
MNTACQ macro 



RPL reason code 13 
RPL return code 13 
RPL L EN parameter 

in FIELDS parameter 143 
RRDS parameter 

in TESTCB macro 147 
RST subparameter 

in MACRF parameter of the ACB macro 
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S-type address constant 33, 69 
SCHBFR macro 

summary 165 
SCRA subparameter, in CRA parameter 

in ACB macro 36 

in GENCB macro 72 

in TESTCB macro 147 

restriction 36, 72 
search argument 

full key 131 

generic (partial) key 129 
SEQ subparameter 

in MACRF parameter of the ACB macro 38 

in OPTCD parameter of RPL macro 128 
sequential insert strategy 

specified in ACB 38 
sequential processing 

reason code positioning state 25 
shared resource macros 

return codes 30 
shared resources 34 
SHAREOPTIONS 4 

incompatible with deferring write requests 3 
sharing 

control blocks 

based on DDNAME 34 
based on DSNAMB 34 

parameter lists 178 

among BLDVRP, DLVRP, GENCB, MODCB, 
SHOVVCB, and TESTCB 171 

reentrant form 178 
SHOWCB macro 

as used with CLOSE macro return codes 6 

display an ACB example 137 

displaying a physical error message example 144 

displaying an access method control block 
example 137 

displaying an exit list address example 1 38 

displaying fields of a request parameter list 141 
summary 166 

displaying fields of an access method control 
summary 166 

displaying fields of an access method control 
block 133 

displaying fields of an exit list 139 
summary 166 

displaying the length of an exit example 140 

execute form 177 

with parameter lists built by user 183 

format 133 

generate form 177 

linking to VSAM directly 187 

list form 177 

operand notation 181 

reason codes 10 

reason codes from OPEN macro 2 

return codes 10 
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SHRPOOL parameter 

ACB macro 41 

BLDVRP macro 47 

DLVRP macro 59 

in GENCB macro 74 
SIS option 

in M ACRF parameter of the ACB macro 39 
skip-sequential processing 

reason code positioning state 25 
SKP subparamcter 

in MACRF parameter of the ACB macro 38 

in OPTCD parameter of RPL macro 128 
SPAN parameter 

in TESTCB macro 147 
SSWD parameter 

in TESTCB macro 147 
STMST parameter 

in FIELDS parameter 137 
storage requirements, I/O buffers 36, 70 
storing a record (PUT macro) 111 
storing an index record 13 
string extension, dynamic 35, 38 
STRMAX parameter 

in FIELDS parameter 135 
STRNO parameter 

BLDVRP macro 48 

in ACB macro 41 
1 in FIELDS parameter 135 

in GENCB macro 74 
summary of macros 159 
suspending processing 

overlap processing 52 

request for many records 53 
SYN subparamcter 

in OPTCD parameter of RPL macro 129, 130 
SYNAD exit routine 

physical error message 26 
SYNAD parameter 

in EXLST macro 67 

in GENCB macro 77 

in SHOWCB macro 140 

in TESTCB macro 150 
synchronizing end of data 

(VERIFY macro) 155 
synchronous processing 

specified in MODCB macro 104 

specified in RPL macro 130 
synchronous request 

return codes 14 







T On TYPE parameter in CLOSE macro) 7 
temporary CLOSE macro 7 
terminating a request 

ENDREQ macro 61 
terminating a request before completion 62 
TESTCB macro 154 



execute form 178 

with parameter lists built by user 183 

format 145, 150 

generate form 178 

linking to VSAM directly 187 

list form 177 

operand notation 181 

reason codes 10 

return codes 10 

testing a field of a request parameter list 
summary 168 

testing a field of an access method control block 
summary 167 

testing a field of an exit list 150 
summary 168 

testing a request parameter list 152 

testing fields of an access method control 
block 145 

testing for data set attributes 148 

using a branch table 151 
testing a control block 

exit list 150 

request parameter list 152 
transaction ID 

writing related requests 1 57 
TRANSID parameter 

in FIELDS parameter 143 

in GENCB macro 83 

in RPL macro 130 
TRANSID subparameter 

SCI IBFR macro 132 
TRN subparamcter 

in WRTBFR macro 157 
TYPE parameter 

BLDVRP-macro 48 

DLVRP macro 59 

in CLOSE macro 7, 55 

in WRTBFR macro 156 



u 



UBF option 

in MACRF parameter of the ACB macro 39 
UCRA subparamcter, in CRA parameter 

in ACB macro 36 

in GENCB macro 72 

in TESTCB macro 147 

restrictions 36, 72 
UIW parameter 

in FIELDS parameter 137 
underlining, in notation convention vii 
UNQ attribute, in ATRB parameter 147 
UPAD parameter 

in EXLST macro 67 
UPD subparameter 

in OPTCD parameter of RPL macro 1 29 
updating records 
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See also storing a record, lengthening a record, and 
shortening a record 

addressed-sequential 1 23 

example 120 

keyed-direct 121 

keyed-sequential 120 
upgrade set 

status following request that fails 14 
upper case, in notation convention vii 
use of list, execute, generate forms 178 
user buffering 39 









VERIFY command 
use in OPEN macro 
reason codes 2 
VERIFY macro 
.••'' format 1 55 
summary 168 
VSAM macro formats and examples 
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WAITX subparameter 

in- €>PTCE> parameteeof RPL macro* 
WAREA parameter 
in GENCB 

generating request parameter list 83 
in GENCB macro 

generating access method control block 
generating exit list 74, 77 
VVCK parameter 



74 



in TESTCB macro 147 
work area 

processing a record in 83, 126 
relation to I/O buffer 83, 126 
specifying 

generating access method control block 74 
generating exit list 77 
generating request parameter list 83 
work data set 

specifying in ACB macro 39 
WRTBFR macro 
format 156 
summary 169 



XINVALID subparameter 
in MRKBFR macro 106 



YES subparameter, in CATALOG parameter 
in ACB macro 36 
in GENCB macro 71 
in TESTCB macro 147 
restriction 36, 71 
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